{ "openapi": "3.1.0", "info": { "title": "Boekhouden API", "version": "0.12.0", "description": "Bearer-only API for the accounting platform, including managed Sales and Purchase documents, payments, supplier credits, refunds, VAT corrections, FX evidence, open items, bank accounts, CAMT.053 imports, explicit bank linking and processing, and reconciliation." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/administrations/{administration_public_id}/bank/provider-payouts": { "post": { "operationId": "postProviderPayout", "summary": "Preview a replacement of an existing own transfer", "description": "Requires banking:write, current owner/manager authority, API entitlement and token allowlist. Checks the union of current and replacement participants; rekening_courant:write is additionally required when either group spans administrations. Requires expected_revision and complete transfer input; no Idempotency-Key or input state_hash. Rejects unknown body/query fields. Read-only preview: no command reservation or financial writes. Returns state_hash, unchanged, both dated journal phases and the clearing movement in the paying administration currency. The same exact retained-inactive bank/route rule and fiscal-year/FX guards as updateBankTransfer apply. A non-zero clearing movement is not automatically posted as costs or FX. Deleted targets return 410; stale revisions return bank_transfer_stale (409). Journal state_hash values are evidence only; confirmation uses the outer mutation state_hash. Under active periodic cash valuation a local v2 source also accepts operation=delete with expected_revision and no transfer input. It returns both original journals to remove and all valuation additions, bound to one state_hash. Confirmation requires that proof. Updates include valuation additions and separate signed native and EUR clearing differences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostProviderPayoutRequest" } } } }, "responses": { "201": { "description": "Stored canonical transfer or current-account source", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProviderPayoutIdentity" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "The target transfer has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/administrations/{administration_public_id}/bank/provider-payouts/preview": { "post": { "operationId": "previewProviderPayout", "summary": "Preview a replacement of an existing own transfer", "description": "Requires banking:write, current owner/manager authority, API entitlement and token allowlist. Checks the union of current and replacement participants; rekening_courant:write is additionally required when either group spans administrations. Requires expected_revision and complete transfer input; no Idempotency-Key or input state_hash. Rejects unknown body/query fields. Read-only preview: no command reservation or financial writes. Returns state_hash, unchanged, both dated journal phases and the clearing movement in the paying administration currency. The same exact retained-inactive bank/route rule and fiscal-year/FX guards as updateBankTransfer apply. A non-zero clearing movement is not automatically posted as costs or FX. Deleted targets return 410; stale revisions return bank_transfer_stale (409). Journal state_hash values are evidence only; confirmation uses the outer mutation state_hash. Under active periodic cash valuation a local v2 source also accepts operation=delete with expected_revision and no transfer input. It returns both original journals to remove and all valuation additions, bound to one state_hash. Confirmation requires that proof. Updates include valuation additions and separate signed native and EUR clearing differences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewProviderPayoutRequest" } } } }, "responses": { "200": { "description": "Provider payout preview", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankProviderPayoutPreview" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "The target transfer has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [] } }, "/administrations/{administration_public_id}/purchases/supplier-credit-writeoffs/{purchase_settlement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSupplierCreditWriteoffUpdate", "summary": "Preview a supplier-credit write-off update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewUpdateSupplierCreditWriteoffRequest" } } } }, "responses": { "200": { "description": "Application plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-credit-writeoffs/{purchase_settlement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "put": { "operationId": "updateSupplierCreditWriteoff", "summary": "Update the same supplier-credit write-off in place", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSupplierCreditWriteoffRequest" } } } }, "responses": { "200": { "description": "Updated application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-credit-writeoffs/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewSupplierCreditWriteoff", "summary": "Preview a supplier-credit write-off", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewSupplierCreditWriteoffRequest" } } } }, "responses": { "200": { "description": "Application plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-credit-writeoffs": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "postSupplierCreditWriteoff", "summary": "Apply a unrecoverable supplier credit without a payment or VAT posting", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierCreditWriteoffRequest" } } } }, "responses": { "201": { "description": "Supplier-credit application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } } } } }, "/administrations/{administration_public_id}/fixed-assets/purchase-candidates": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listFixedAssetPurchaseCandidates", "summary": "List purchases still available for the asset register", "description": "Requires BOTH fixed_assets:read and purchases:read, current administration access, API entitlement and token allowlist. No create permission required for these reads. Only live purchases on active base-only, debit-normal fixed-asset accounts are candidates. Exact historical VAT/FX cost less ALL current allocations (including future and disposed assets). No booking or allocation is made. Descending purchase-line public ID, signed administration-bound cursors. Broken historical evidence remains visible with error_code and null available_amount. No empty intermediate pages caused by fully claimed purchases.", "responses": { "200": { "description": "Read-only result; preview and confirmation still use the existing asset commands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetPurchaseCandidateListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" } ] } }, "/administrations/{administration_public_id}/fixed-assets/purchase-candidates/{line_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "line_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "prepareFixedAssetPurchase", "summary": "Prepare an existing purchase in the shared asset workflow", "description": "Requires BOTH fixed_assets:read and purchases:read, current administration access, API entitlement and token allowlist. No create permission required for these reads. Only live purchases on active base-only, debit-normal fixed-asset accounts are candidates. Exact historical VAT/FX cost less ALL current allocations (including future and disposed assets). No booking or allocation is made. Returns the current available amount, source dates and uniquely compatible account suggestions, not a complete create request. Supply the unknown asset kind, dates, residual value and life explicitly; preview and confirm using the existing fixed-assets endpoints. Fully claimed or no-longer-eligible sources return 404.", "responses": { "200": { "description": "Read-only result; preview and confirmation still use the existing asset commands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetPurchasePreparationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/fixed-assets": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listFixedAssets", "summary": "List fixed assets", "description": "Requires fixed_assets:read, current access, API entitlement and token allowlist. Descending public identity order; opaque cursors are administration-bound.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" } ] }, "post": { "operationId": "createFixedAsset", "summary": "Create an asset after preview", "description": "Requires fixed_assets:write, current owner/manager access, API entitlement and token allowlist. All purchase identities must belong to the administration. Confirm the full editable input using the current state_hash and an Idempotency-Key. Assets, due journals, other affected assets, audit and command commit or roll back together. Exact replay requires current rights and returns the recorded snapshot with Idempotency-Replayed=true. Changed key input or stale revisions/previews return 409. A true semantic no-op creates no revision, audit or command. Omitted disposal preserves it on update; null explicitly undoes it.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetCreateRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetResponse" } } }, "headers": { "Idempotency-Replayed": { "description": "Present with value true only when returning an exact previously completed command.", "schema": { "type": "string", "const": "true" } } } }, "201": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetResponse" } } }, "headers": { "Idempotency-Replayed": { "description": "Present with value true only when returning an exact previously completed command.", "schema": { "type": "string", "const": "true" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/fixed-assets/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewFixedAsset", "summary": "Preview an asset without writes", "description": "Requires fixed_assets:write, current owner/manager access, API entitlement and token allowlist. All purchase identities must belong to the administration. Read-only; no idempotency key consumed. An incomplete VAT split returns required choices, not permission to save.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetCreatePreviewRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/fixed-assets/{asset_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "asset_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getFixedAsset", "summary": "Read an asset and its source evidence", "description": "Requires fixed_assets:read, current access, API entitlement and token allowlist. Cross-administration identities are not revealed.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateFixedAsset", "summary": "Update an asset and its dependent postings", "description": "Requires fixed_assets:write, current owner/manager access, API entitlement and token allowlist. All purchase identities must belong to the administration. Confirm the full editable input using the current state_hash and an Idempotency-Key. Assets, due journals, other affected assets, audit and command commit or roll back together. Exact replay requires current rights and returns the recorded snapshot with Idempotency-Replayed=true. Changed key input or stale revisions/previews return 409. A true semantic no-op creates no revision, audit or command. Omitted disposal preserves it on update; null explicitly undoes it.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetUpdateRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetResponse" } } }, "headers": { "Idempotency-Replayed": { "description": "Present with value true only when returning an exact previously completed command.", "schema": { "type": "string", "const": "true" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/fixed-assets/{asset_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "asset_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewFixedAssetUpdate", "summary": "Preview an asset replacement", "description": "Requires fixed_assets:write, current owner/manager access, API entitlement and token allowlist. All purchase identities must belong to the administration. Requires expected_revision and full editable input. No writes or command key. Retain identities of source-derived VAT changes; their financial basis cannot be deleted or redated as an ordinary estimate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetUpdatePreviewRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAssetPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/transfers/{transfer_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "transfer_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankTransfer", "summary": "Read an existing own transfer or its minimal deleted state", "description": "Requires banking:read, current actual access, API entitlement and token allowlist. The administration in the path is the paying/source administration. Every administration with a current owned journal must remain accessible through the token; more than one current participant additionally requires rekening_courant:read. One shared source lock covers participant authorization and the read projection. No request body or query fields. Returns stored transfer input, resolved route amounts and current journal identities, not editable account or route choices. Deleted transfers retain only identity, revision, source administration and deleted=true; target, transfer and edge_amounts are null and journals is empty. Does not restore deleted financial contents.", "responses": { "200": { "description": "Current transfer projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransferResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateBankTransfer", "summary": "Update the same own transfer in place", "description": "Requires banking:write, current owner/manager authority, API entitlement and token allowlist. A new execution authorizes the union of old and replacement participants; rekening_courant:write is required when either group spans administrations. Requires expected_revision, the complete transfer input, the current preview state_hash and an Idempotency-Key. Rejects unknown body/query fields. Retains transfer identity and journal identities/numbers for surviving roles; removed roles retain only minimal deleted identities. An exactly retained inactive bank account in its original role or exact existing route is allowed; new choices must be active. The explicit clearing account remains base-currency-only in the paying administration. Both real dates and existing fiscal-year/FX dependency guards apply. Semantically unchanged input does not rewrite financial facts or increment revisions, but the completed command identity is retained. Financial changes, audits and command identity commit or roll back together. Same-principal exact-key/payload replay returns only the current public_id/revision without replanning or disclosing remote facts; current local rights and token validity remain required. It returns 410 if that transfer was subsequently deleted. Reusing a key with different input returns bank_command_key_conflict (409); stale revision or preview returns bank_transfer_stale (409). Existing bank links are not removed automatically and may need review. Does not promise an Idempotency-Replayed response header.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransferUpdateRequest" } } } }, "responses": { "200": { "description": "Current identity and revision only, including replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransferIdentityResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "The target transfer has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteBankTransfer", "summary": "Remove transfer financial contents and preserve minimal identity", "description": "Requires banking:write, current owner/manager authority, API entitlement and token allowlist. New execution checks all current participants and additionally rekening_courant:write for a cross-administration transfer. Requires expected_revision and an Idempotency-Key; no preview state_hash. Rejects unknown body/query fields. Existing fiscal-year and FX dependency guards apply; inactive bank accounts or routes alone do not block deletion. Clears financial input, route amounts and owned journal contents, keeping minimal transfer/journal identities. Imported bank entries and existing bank links remain; affected links require review rather than silent unlinking. All deletion effects, audits and command identity commit or roll back together. Exact completed replay returns 204 without re-running financial checks or returning remote data; current local rights and token validity remain required. A new deletion command against an already deleted target returns 410. Changed input for a used key returns bank_command_key_conflict (409); a stale expected_revision returns bank_transfer_stale (409). Does not promise an Idempotency-Replayed response header. For a periodic v2 source, first preview operation=delete at the existing preview endpoint and confirm its state_hash. The complete source and valuation appendix must remain unchanged; stale proof is rejected without writes.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransferDeleteRequest" } } } }, "responses": { "204": { "description": "Deletion completed or the exact completed deletion replayed; no response body" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "The target transfer has already been deleted for a new command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/transfers/{transfer_public_id}/form-data": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "transfer_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankTransferFormData", "summary": "Read the same stored transfer projection for editing", "description": "Requires banking:read and exactly the same current participant access, API entitlement, token allowlist and conditional rekening_courant:read as getBankTransfer. No request body or query fields. This existing endpoint returns the same BankTransferResponse as detail: stored transfer input, resolved route amounts and current journal identities. It does not return candidate accounts, route choices, a preview state_hash or permission to commit. Deleted financial input remains null. Preview and update perform their own current authorization and validation.", "responses": { "200": { "description": "Same current projection as getBankTransfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransferResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/transfers/{transfer_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "transfer_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankTransferUpdate", "summary": "Preview a replacement of an existing own transfer", "description": "Requires banking:write, current owner/manager authority, API entitlement and token allowlist. Checks the union of current and replacement participants; rekening_courant:write is additionally required when either group spans administrations. Requires expected_revision and complete transfer input; no Idempotency-Key or input state_hash. Rejects unknown body/query fields. Read-only preview: no command reservation or financial writes. Returns state_hash, unchanged, both dated journal phases and the clearing movement in the paying administration currency. The same exact retained-inactive bank/route rule and fiscal-year/FX guards as updateBankTransfer apply. A non-zero clearing movement is not automatically posted as costs or FX. Deleted targets return 410; stale revisions return bank_transfer_stale (409). Journal state_hash values are evidence only; confirmation uses the outer mutation state_hash. Under active periodic cash valuation a local v2 source also accepts operation=delete with expected_revision and no transfer input. It returns both original journals to remove and all valuation additions, bound to one state_hash. Confirmation requires that proof. Updates include valuation additions and separate signed native and EUR clearing differences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransferUpdatePreviewRequest" } } } }, "responses": { "200": { "description": "Current replacement preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransferUpdatePreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "The target transfer has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}/proposals": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "listBankProposals", "summary": "Read explainable exact-reference bank proposals", "description": "Requires banking:read, current actual membership/ownership, API entitlement and token allowlist. By default searches both Purchases and Sales within the caller's module read permissions (purchases:read and sales:read, as available). Optional module filters sales/purchases require that module's read ability. General bank access is checked independently; revoked or expired access is never treated as partial search. All-module responses identify searched_modules and coverage.modules_limited; no permitted module yields 403. Current rights are checked before source queries. Unknown query/body fields are rejected; no request body. Suggestions only: no writes, reservations, automatic selection, confirmation flag, state_hash or Idempotency-Key. Exact case-sensitive document reference evidence is matched as a full source value or a delimited token; no fuzzy names, amount-only matching, normalization or hidden priority. Only matching cash-flow directions produce suggestions. Paid documents remain discoverable through their already-posted settlement bank legs. Source capacity and existing links are respected; incomplete, ambiguous or partial suggestions do not invent an amount, split, difference treatment or FX rate. Combined search assesses ambiguity across both modules before publishing any proposed amounts. The original lexical bank booking day may be offered explicitly, never a document-date fallback. Returned operation input additionally requires banking:write and the target module's write ability; otherwise input is empty and missing_fields contains permission. A selected proposal still requires the existing financial preview and explicit single-entry or batch confirmation with fresh authorization and capacity checks. Each page covers up to 10 matched documents per permitted module, not 10 proposals; one document may produce multiple proposals. All-module page N combines page N from each module, with last_page equal to the maximum module page count; exhausted modules return no repeated rows. per_page is the combined document capacity (10 or 20). Reference and related-source caps are disclosed in coverage. Uniqueness is never implied after an incomplete search.", "parameters": [ { "name": "module", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "sales", "purchases" ], "default": "all" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } } ], "responses": { "200": { "description": "Current read-only proposals and search coverage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankProposalCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/entries/processing/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewBankBatchProcessing", "summary": "Preview one explicitly selected ordered bank-entry batch", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Existing links require the matching domain read ability; operations require the same domain write and participant permissions as single-entry processing. Rejects unknown body/query fields. A read-only preview for 1..100 distinct entries of this administration and at most 100 operations in total. Submitted entry order and operation order are preserved; nothing is sorted or matched automatically. All operations share pending journal numbers, native/carrying/RC positions, document and credit usage, and duplicate-purchase facts. Old links of all selected entries are replaced together; unselected claims and earlier planned final claims still consume capacity. Returns one joint state_hash and local entry/operation addresses. Duplicate acknowledgements use zero-based command-global operation_index, equal to operation_offset plus local index. Errors use entries.i.operations.j.data.field or entries.i.links.j.field. No writes, temporary IDs or Idempotency-Key. Each entry uses existing ULID links or its own new operations: there is no operation-reference from another entry and no automatic matching. In particular, a second side of a newly created transfer must be linked after that transfer exists, not through an invented batch reference.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankBatchPreviewRequest" } } } }, "responses": { "200": { "description": "Current joint preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankBatchPreview" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/entries/processing": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "processBankBatch", "summary": "Confirm one atomic ordered bank-entry batch", "description": "Requires banking:write plus the same current domain permissions and token scope as previewBankBatchProcessing. Requires the joint state_hash and an Idempotency-Key. Canonical locks recheck all scopes and facts. All financial operations, links, numbering, audits and command identity commit or roll back together in one transaction; this is not a loop of independent commands. Uses submitted order and exactly the previewed shared financial plan; there is no automatic matching or operation-reference between entries. Existing link sources must already have real ULIDs. Replaying the same key and payload returns the current ordered selected bank entries without replanning or duplicating financial writes, even if financial sources were subsequently deleted. Current actor/token rights remain required. A deleted selected bank entry returns 410; changed payload with a used key returns bank_command_key_conflict. Does not promise an Idempotency-Replayed response header. Child command hashes are not accepted; the optional existing manual fx_state_hash retains its normal validation.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Caller-generated key for the whole ordered batch; reuse exactly the same key and payload after an uncertain response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankBatchRequest" } } } }, "responses": { "200": { "description": "Current bank entries in submitted order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankBatchResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "A previously completed batch entry no longer exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/rules": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listBankRules", "description": "Requires banking:read, current tenant access, API entitlement and token allowlist. No body; unknown query/body fields rejected. Follow links.next for cursor pagination; inaccessible operation is null. Bank account deletion retains rules as unavailable.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } } ] }, "post": { "operationId": "createBankRule", "description": "Requires banking:write and current owner/manager permission plus source-module write access in every participant. Idempotency-Key and expected_revision required (0 for creation). bank_rule_stale or bank_command_key_conflict returns 409; deleted replay target returns 410. Exact completed replay returns the currently authorized resource, operation=null without read rights. No-op creates no audit or revision. No financial writes and no automatic posting. Does not promise an Idempotency-Replayed header.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleInput" } } } }, "responses": { "201": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/rules/form-data": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "bankRuleFormData", "description": "Requires banking:read, current tenant access, API entitlement and token allowlist. No body; unknown query/body fields rejected. Also requires banking:write and source-module write rights. Reusable choices only; no financial defaults.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleFormData" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "type", "in": "query", "required": true, "schema": { "enum": [ "sales_receipt", "sales_refund", "sales_customer_credit_refund", "sales_document", "purchase_payment", "purchase_supplier_refund", "purchase_document", "manual_journal", "bank_transfer", "loan", "purchase_payroll_refund" ] } }, { "name": "administration_public_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ] } }, "/administrations/{administration_public_id}/bank/rules/{rule_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "rule_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "showBankRule", "description": "Requires banking:read, current tenant access, API entitlement and token allowlist. No body; unknown query/body fields rejected. Inaccessible source input is operation=null.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateBankRule", "description": "Requires banking:write and current owner/manager permission plus source-module write access in every participant. Idempotency-Key and expected_revision required (0 for creation). bank_rule_stale or bank_command_key_conflict returns 409; deleted replay target returns 410. Exact completed replay returns the currently authorized resource, operation=null without read rights. No-op creates no audit or revision. No financial writes and no automatic posting. Does not promise an Idempotency-Replayed header.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleInput" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteBankRule", "description": "Requires banking:write and current owner/manager permission. Deletes only the rule; earlier postings remain. Current expected_revision and Idempotency-Key required. Exact completed replay returns 204; stale revision or changed key input returns 409. No tombstone or financial writes.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRevisionRequest" } } } }, "responses": { "204": { "description": "Rule deleted" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}/rules": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "suggestBankRules", "description": "Requires banking:read, current tenant access, API entitlement and token allowlist. No body; unknown query/body fields rejected. Suggestions only, no writes. Each suggested operation additionally requires current banking:write and source-module write permissions. All eligible matches are paginated at 20 per page; literal same-detail evidence. No amount matching, hidden priority or automatic choice.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRuleSuggestionPage" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } } ] } }, "/administrations/{administration_public_id}/bank/accounts": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listBankAccounts", "summary": "List bank accounts", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. Follow links.next for keyset pagination. Cursors encode public_id (or statement position on import detail) and a boolean direction; they are not signed scope tokens. Scope is independently enforced on every request. No request body. ", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createBankAccount", "summary": "Create a bank account", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. expected_revision must be 0. Inline ledger creation also requires ledger_accounts:write, uses the standard RGS mapping for the chosen type and is atomic with the bank account. IBAN uses the existing comparison rules; other identities compare exactly. No opening balance or financial posting is created. Account changes, their audit and completed command are atomic. No separate Broker cash source is created or synchronized.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "responses": { "201": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCreateInput" } } } } } }, "/administrations/{administration_public_id}/bank/accounts/form-data": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getBankFormData", "summary": "Read bank-account form choices", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. No request body. No account is selected automatically. An ineligible current ledger remains identifiable. routing_locked and can_delete reflect current source data; both lock reasons are always present. Reasons describe existing financial source use, statement imports and live Broker use. Active owner sources retain the account identity, purpose, currency and ledger link even after unlink and import deletion. Name, starting date and active status remain editable. Removed owner tombstones do not lock an account. No separate Broker cash registration needs detaching. A new account has can_delete=false and both reasons null. Form-data reason priority for both fields is settlement, transfer, import, broker, vat, tax, balance, owner. When no existing account is selected, can_delete=false and both reasons null. Statements control the routing import reason, while statements or entries control its delete reason. These form-data priorities do not redefine update or delete command error order.", "parameters": [ { "name": "account_public_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankFormData" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/accounts/{account_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "account_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankAccount", "summary": "Read a bank account", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. No query or request body.", "parameters": [], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateBankAccount", "summary": "Update a bank account", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Full replacement with current expected_revision. Identity, currency and ledger routing cannot change after statement import, while the account participates in an active own transfer, or while live Broker transactions, opening positions, receiving transfer depots or payments use that Bank account. All Broker actions and instrument kinds use the same protection; removed sources without live account references do not lock routing. Broker financial history returns bank_account_has_broker_history (409). Name, starting date and active status remain editable. Active transfer routing changes return bank_account_has_transfer_history (409); import history returns bank_account_has_import_history (409). A no-op does not increment revision. No financial entries are changed. Account changes, their audit and completed command are atomic. No separate Broker cash source is created or synchronized. All ordinary Bank account changes require banking:write; there is no additional investments:write bridge permission. Existing use errors: bank_account_has_settlement_history (409), bank_account_has_transfer_history (409), bank_account_has_import_history (409), bank_account_has_broker_history (409), bank_account_has_vat_payments (409), bank_account_has_tax_movements (409), bank_account_has_balance_movements (409), bank_account_has_owner_movements (409). Use-check order is settlement, transfer, vat, owner, balance, tax, then account preparation, import and broker. Input, access, replay, revision and account eligibility checks may fail earlier; this is not an unconditional global error priority. Import history preserves the existing IBAN comparison and protects identity, currency and ledger linkage. Other live-source guards keep their existing routingChanged field boundary. No lock is added or relaxed.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountInput" } } } } }, "delete": { "operationId": "deleteBankAccount", "summary": "Delete an unused bank account", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Only accounts without statements, entries, active settlements, active own transfers, live Broker use or active VAT, owner, balance or tax movements may be deleted; live Broker use includes transactions of every instrument kind, opening positions, receiving transfer depots and payments. Removed sources without live account references do not prevent deletion; current expected_revision is mandatory. Active transfer involvement returns bank_account_has_transfer_history (409); import history returns bank_account_has_import_history (409); live Broker use returns bank_account_has_broker_history (409). Deleting an unused Bank registration preserves its ledger account. Financial postings and their evidence are not deleted by this command. Account changes, their audit and completed command are atomic. No separate Broker cash source is created or synchronized. Existing use errors: bank_account_has_settlement_history (409), bank_account_has_transfer_history (409), bank_account_has_import_history (409), bank_account_has_broker_history (409), bank_account_has_vat_payments (409), bank_account_has_tax_movements (409), bank_account_has_balance_movements (409), bank_account_has_owner_movements (409). Delete use-check order is settlement, transfer, import, broker, vat, owner, balance, tax. Statements or entries count as imported history. Access, replay and revision checks still run before these use checks; form-data uses its own documented reason priority.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "responses": { "204": { "description": "Completed without a response body" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRevisionRequest" } } } } } }, "/administrations/{administration_public_id}/bank/accounts/{account_public_id}/entries": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "account_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "listBankEntries", "summary": "List imported bank entries", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. Follow the returned links for keyset pagination. Search q matches literal case-insensitive text in stored descriptions, bank references, counterparty names/accounts, remittance text/references and transaction references; percent, underscore and backslash are literal characters, not wildcard instructions. JSON field names are not searched. Entries without a bank booking date come first, followed by reported calendar date descending. Equal dates retain statement order from each entry's oldest surviving import source; deleting that import makes the next surviving source determine order. The opaque cursor contains this complete public ordering tuple and a boolean direction, with no internal database IDs; it is not a signed scope token. Scope is independently enforced on every request. No request body. Date filters use the bank's reported calendar date without timezone conversion. Linked does not prove account reconciliation.", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "through", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "link_filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "unlinked", "open" ], "default": "all" }, "description": "unlinked: no surviving bank link. open: exact signed entry amount minus all linked amounts differs from zero, including stale links. Filter is applied before pagination; it is not an account reconciliation." }, { "name": "allocation_filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "outstanding" ], "default": "all" }, "description": "outstanding requires purchases:read in addition to banking:read. Selects payments with an exact positive stored supplier-advance remainder, within the token administration allowlist and all active journal participants. Independent of link_filter. Applied before pagination. Stored stale bank links may remain candidates requiring review; this is not bank reconciliation or a new payment. Default response payload is unchanged." } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankEntryCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/accounts/{account_public_id}/reconciliation": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "account_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankReconciliation", "summary": "Compare the dated bank and ledger balances", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. Explicit as_of_date is mandatory. No request body, pagination or write. Complete aggregate: equal balances are separate from complete source coverage and current fully processed entries. Missing bank evidence returns null, never zero. Foreign-account balances use native currency. Valid comparable statement periods from exact midnight through whole-second 23:59:59 include the final calendar day; absent or all-zero fractions are accepted, nonzero fractions and partial days are not promoted. Original source values and timezone comparison rules remain unchanged. Timestamp-only balances are not treated as proven day-end balances.", "parameters": [ { "name": "as_of_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankReconciliation" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankEntry", "summary": "Read one bank entry and its links", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. No query or request body. Preserves source status, reversal, batch and charge evidence. Links can become needs_review after a source edit/delete.", "parameters": [], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankEntryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}/candidates": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "listBankFinancialCandidates", "summary": "Search existing financial bank legs", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. Additionally requires the selected source's read ability: sales:read, purchases:read, journal_entries:read, rekening_courant:read, investments:read for Broker settlements or banking:read for own transfers. Suggestions only, never reserved or automatically selected. Explicit direction supports opposing signed legs for net/charge splits. Capacity and source freshness are rechecked on confirmation. No request body. total counts the underlying page candidates; concurrent/unavailable sources may yield fewer data items.", "parameters": [ { "name": "source_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/BankSourceType" } }, { "name": "direction", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/BankDirection" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "maxLength": 120 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankFinancialCandidateCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/imports": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listBankImports", "summary": "List bank import metadata", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. Follow links.next for keyset pagination. Cursors encode public_id (or statement position on import detail) and a boolean direction; they are not signed scope tokens. Scope is independently enforced on every request. No request body. No source-file bytes in the metadata response.", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankImportCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "confirmBankImport", "summary": "Confirm a reviewed CAMT.053 import", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Requires the preview state_hash and explicit mappings/ambiguous choices. Exact repeated files reuse the existing import when mappings agree. Persists bank source data only, never financial journals. Original bytes are encrypted at rest. CAMT inspect, preview and import share a platform-configurable per-user minute limit across tokens, administrations and the website (default 30, range 1–300). Failed attempts count. Existing API limits also apply; HTTP 429 includes Retry-After.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "responses": { "201": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankImportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file", "import" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CAMT.053 XML, maximum 5120 KiB. Unsupported format/version or unsafe XML is rejected. Only attribute-free and childless Ustrd elements at Document/BkToCstmrStmt/Stmt/Ntry/NtryDtls/TxDtls/RmtInf/Ustrd in the declared supported namespace are treated as absent optional remittances in memory; XSD validation stays enabled. Whitespace, other content and required values are not repaired. Hashing, retention and download use the original bytes." }, "import": { "$ref": "#/components/schemas/BankImportConfirmInput" } } } } } } } }, "/administrations/{administration_public_id}/bank/imports/{import_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "import_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankImport", "summary": "Read import metadata and statements", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. Follow links.next for keyset pagination. Cursors encode public_id (or statement position on import detail) and a boolean direction; they are not signed scope tokens. Scope is independently enforced on every request. No request body. Statement cursors use position. Original source-file bytes are available only at /file.", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankImportDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteBankImport", "summary": "Delete an import or its original file", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Requires current preview state_hash. file_only=true removes original bytes but retains import/source rows. Full deletion is blocked while affected entries have links; shared entries with other source occurrences are retained. Does not delete financial postings.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "responses": { "204": { "description": "Completed without a response body" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankImportDeletionRequest" } } } } } }, "/administrations/{administration_public_id}/bank/imports/{import_public_id}/file": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "import_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "downloadBankImportFile", "summary": "Download the original CAMT file", "description": "Requires banking:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Unknown query/body fields are rejected. No query or request body. Returns original bytes as attachment with application/octet-stream, private no-store and nosniff. 410 if the source file has been explicitly deleted.", "parameters": [], "responses": { "200": { "description": "Original CAMT file", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "bank_source_file_deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/imports/inspect": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "inspectBankImport", "summary": "Inspect a CAMT.053 file", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. No persisted import or financial writes. No Idempotency-Key required. CAMT inspect, preview and import share a platform-configurable per-user minute limit across tokens, administrations and the website (default 30, range 1–300). Failed attempts count. Existing API limits also apply; HTTP 429 includes Retry-After.", "parameters": [], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankInspectionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CAMT.053 XML, maximum 5120 KiB. Unsupported format/version or unsafe XML is rejected. Only attribute-free and childless Ustrd elements at Document/BkToCstmrStmt/Stmt/Ntry/NtryDtls/TxDtls/RmtInf/Ustrd in the declared supported namespace are treated as absent optional remittances in memory; XSD validation stays enabled. Whitespace, other content and required values are not repaired. Hashing, retention and download use the original bytes." } } } } } } } }, "/administrations/{administration_public_id}/bank/imports/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewBankImport", "summary": "Preview mapped import rows or duplicate candidates", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. No persisted import or financial writes. No Idempotency-Key required. Normal rows use 50 per page; with row=statement:position return that row's duplicate candidates, 20 per page. Nested import fields use multipart field names, e.g. import[mappings][0][statement]. CAMT inspect, preview and import share a platform-configurable per-user minute limit across tokens, administrations and the website (default 30, range 1–300). Failed attempts count. Existing API limits also apply; HTTP 429 includes Retry-After.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "row", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+:[0-9]+$" } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankImportPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file", "import" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CAMT.053 XML, maximum 5120 KiB. Unsupported format/version or unsafe XML is rejected. Only attribute-free and childless Ustrd elements at Document/BkToCstmrStmt/Stmt/Ntry/NtryDtls/TxDtls/RmtInf/Ustrd in the declared supported namespace are treated as absent optional remittances in memory; XSD validation stays enabled. Whitespace, other content and required values are not repaired. Hashing, retention and download use the original bytes." }, "import": { "$ref": "#/components/schemas/BankImportInput" } } } } } } } }, "/administrations/{administration_public_id}/bank/imports/{import_public_id}/deletion-preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "import_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankImportDeletion", "summary": "Preview deleting an import or only its file", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. No writes or Idempotency-Key required. file_only explicitly distinguishes original-file removal from full import removal.", "parameters": [], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankImportDeletionPreview" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankImportDeletionPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}/links/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankLinks", "summary": "Preview replacement links", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Requires the read ability of every supplied financial source. No writes or Idempotency-Key. links is the complete replacement list, not a patch. Empty links previews unlinking without changing financial postings.", "parameters": [], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankLinksPreview" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankLinksPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}/links": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "put": { "operationId": "replaceBankLinks", "summary": "Replace entry links without creating postings", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Requires each financial source read ability and current preview state_hash. The entire link set is replaced atomically. Empty links unlinks all sources without deleting their financial postings. Source/entry/account/currency/direction/capacity and current permissions are rechecked.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankEntryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankLinksRequest" } } } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}/processing/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankProcessing", "summary": "Preview existing links and new financial operations", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Requires each existing link source's read ability. New operations require sales:write, purchases:write, journal_entries:write or banking:write for own transfers; Sales RC/linked-administration operations and cross-administration own transfers also require rekening_courant:write. Current permissions and token scope cover every participating administration. Only the listed operation types exist; invoice issuance is not an operation. Own transfers use BankTransferInput with both bank dates and an explicit paying-side clearing account; current-account postings happen on arrival. Ordered operations see earlier pending journals/open-item usage/EU-B2C turnover. New documents require their explicit receipt/payment, and only that settlement supplies bank legs. Inputs use their existing closed module contracts, without child state_hash; the outer state_hash protects the complete plan. A manual journal may carry its optional fx_state_hash. VIES proof must already be supplied; no remote VIES lookup happens here. Read-only; no Idempotency-Key. Does not create provisional rows or IDs.", "parameters": [], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankProcessingPreview" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankProcessingPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/bank/entries/{entry_public_id}/processing": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "processBankEntry", "summary": "Atomically post operations and replace links", "description": "Requires banking:write and current owner/manager permission, API entitlement and token allowlist. Current access is checked again under locks. Unknown query/body fields are rejected. Requires each existing link source's read ability. New operations require sales:write, purchases:write, journal_entries:write or banking:write for own transfers; Sales RC/linked-administration operations and cross-administration own transfers also require rekening_courant:write. Current permissions and token scope cover every participating administration. Only the listed operation types exist; invoice issuance is not an operation. Own transfers use BankTransferInput with both bank dates and an explicit paying-side clearing account; current-account postings happen on arrival. Ordered operations see earlier pending journals/open-item usage/EU-B2C turnover. New documents require their explicit receipt/payment, and only that settlement supplies bank legs. Inputs use their existing closed module contracts, without child state_hash; the outer state_hash protects the complete plan. A manual journal may carry its optional fx_state_hash. VIES proof must already be supplied; no remote VIES lookup happens here. Requires the reviewed outer state_hash and Idempotency-Key. All financial writes, audits and final link replacements commit together or roll back together. Replay rechecks current authorization without replanning completed financial operations.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "description": "Required for writes, not previews. Reuse the same key and payload to prevent duplicate execution. Bank commands return the current scoped resource after replay; they do not promise an Idempotency-Replayed response header." } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankEntryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "description": "Previously completed command target was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankProcessingRequest" } } } } } }, "/administrations/{administration_public_id}/invoice-branding": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getInvoiceBranding", "summary": "Read current central invoice appearance and payment instructions", "description": "Requires sales:read, current tenant access and token scope, rechecked under administration locks. No query or body. Full current logo only here, never in document/draft/replay resources.", "responses": { "200": { "description": "Current central invoice appearance and payment instructions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceBranding" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateInvoiceBranding", "summary": "Update central invoice appearance and payment instructions", "description": "Requires sales:write and current owner/manager permission. expected_revision protects concurrent changes. No-op does not advance revision. No financial document revision or fiscal-year mutation. Regenerated documents use current font, accent and logo; open invoices additionally use current explicit payment instructions and outstanding amount. Previously downloaded/sent files stay unchanged. No archive. Optional keys omitted preserve, null clears. No query or Idempotency-Key needed for this revision-based setting. Stale settings return validation error. All branding saves, with or without a logo, share a platform-configurable per-user minute limit across tokens, administrations and the website (default 10, range 1–300). Failed attempts count. Existing API limits also apply; HTTP 429 includes Retry-After.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvoiceBrandingRequest" } } } }, "responses": { "200": { "description": "Current central invoice appearance and payment instructions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceBranding" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/{document_public_id}/presentation": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getInvoicePresentation", "summary": "Read document language and note", "description": "Requires sales:read, current tenant access, API entitlement and token allowlist. Active issued documents only. No query or body.", "responses": { "200": { "description": "Current document language, note and revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePresentationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateInvoicePresentation", "summary": "Update document language and note", "description": "Requires sales:write and current owner/manager rights rechecked under Sales locks. Existing fiscal-year edit boundaries remain. Financial facts stay unchanged. A change advances document revision and invalidates queued mail fingerprints. No branding fields accepted. Same Idempotency-Key and payload replays the result.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvoicePresentationRequest" } } } }, "responses": { "200": { "description": "Updated document with projected presentation, no logo bytes", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-reminders": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listInvoiceReminders", "summary": "Read current overdue issued invoices ready for a reminder", "description": "Requires sales:read and current actual tenant access, API entitlement and token allowlist. Only active issued invoices with a real past due date and positive current receivable are included. Cursor scans are bounded; an empty result can still have a next link. Exact amounts and state hashes are computed in bulk. Preparing this list makes no financial writes and sends nothing. Recipient changes in a manual request never change the Contact.", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceReminderCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current invoice, reminder settings, outstanding balance or mail state changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-reminder-settings": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getInvoiceReminderSettings", "summary": "Read automatic reminder settings", "description": "Requires invoices:send plus current actual tenant access and token allowlist. Missing settings are revision 0, automatic false and an empty day list. No credentials or execution-principal details are returned.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceReminderSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current invoice, reminder settings, outstanding balance or mail state changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "saveInvoiceReminderSettings", "summary": "Save explicit automatic reminder settings", "description": "Requires invoices:send, current owner/manager rights, API entitlement and token allowlist, rechecked under locks. Complete settings replacement with expected_revision; no Idempotency-Key is required for these settings. No dates or costs are invented. Highest currently reached interval only after interruption; paid invoices and uncertain prior automatic deliveries never trigger a new automatic reminder. The configured own SMTP transport remains mandatory.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveInvoiceReminderSettingsRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceReminderSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current invoice, reminder settings, outstanding balance or mail state changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/{document_public_id}/reminder-preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "previewInvoiceReminder", "summary": "Read current reminder amount, recipient suggestion and state guard", "description": "Requires invoices:send and current owner/manager access. Checks current receivable and real past due date, with no financial writes or sending. settings_revision is 0 if own SMTP has not been configured. The suggested recipient may be changed explicitly in the manual sending request.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceReminderPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current invoice, reminder settings, outstanding balance or mail state changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/{document_public_id}/reminders": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "requestInvoiceReminder", "summary": "Request one payment reminder through own SMTP", "description": "Requires invoices:send and current owner/manager rights. A fresh reminder snapshot must match document revision, reminder settings, real due date and exact outstanding amount. All financial/current authorization checks run again at request, claim and immediately before transport. No invoice changes, interest, fees, fallback platform mail or additional financial entries. Read sending status through the existing invoice delivery resource. Reusing the same Idempotency-Key and payload does not queue another message.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestInvoiceReminder" } } } }, "responses": { "200": { "description": "Same sending request replayed without another message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "202": { "description": "Reminder request queued; not proof of SMTP acceptance or inbox delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current invoice, reminder settings, outstanding balance or mail state changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-recurrences": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listInvoiceRecurrences", "summary": "List recurring invoice series", "description": "Requires sales:read, current actual tenant access, API entitlement and token allowlist. Web support grants no API access. No template payload, credentials or execution-principal details are exposed.", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current state conflicts with the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "saveInvoiceRecurrence", "summary": "Create or update a recurring invoice series", "description": "Requires sales:write and current owner/manager access; opting into automatic sending additionally requires invoices:send. Current rights and token allowlist are rechecked under locks. The stable public_id and expected_revision prevent stale or duplicate writes; no Idempotency-Key is needed for schedule management. Financial finalization and delivery retain their existing idempotent command contracts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveInvoiceRecurrenceRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current state conflicts with the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-recurrences/{recurrence_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "recurrence_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getInvoiceRecurrence", "summary": "Read one recurring invoice series", "description": "Requires sales:read, current actual tenant access, API entitlement and token allowlist. Web support grants no API access. No template payload, credentials or execution-principal details are exposed.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current state conflicts with the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-recurrences/{recurrence_public_id}/occurrences": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "recurrence_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "listInvoiceRecurrenceOccurrences", "summary": "Read generated drafts and invoices for a series", "description": "Requires sales:read, current actual tenant access, API entitlement and token allowlist. Web support grants no API access. No template payload, credentials or execution-principal details are exposed.", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceOccurrenceCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current state conflicts with the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-recurrences/{recurrence_public_id}/pause": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "recurrence_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "pauseInvoiceRecurrence", "summary": "Pause a recurring invoice series", "description": "Requires sales:write and current owner/manager access; opting into automatic sending additionally requires invoices:send. Current rights and token allowlist are rechecked under locks. The stable public_id and expected_revision prevent stale or duplicate writes; no Idempotency-Key is needed for schedule management. Financial finalization and delivery retain their existing idempotent command contracts. Resuming after an intentional pause skips missed dates. Ending does not change existing drafts or invoices. Technical downtime creates missed occurrences as drafts only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceTransitionRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current state conflicts with the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-recurrences/{recurrence_public_id}/resume": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "recurrence_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "resumeInvoiceRecurrence", "summary": "Resume a recurring invoice series", "description": "Requires sales:write and current owner/manager access; opting into automatic sending additionally requires invoices:send. Current rights and token allowlist are rechecked under locks. The stable public_id and expected_revision prevent stale or duplicate writes; no Idempotency-Key is needed for schedule management. Financial finalization and delivery retain their existing idempotent command contracts. Resuming after an intentional pause skips missed dates. Ending does not change existing drafts or invoices. Technical downtime creates missed occurrences as drafts only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceTransitionRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current state conflicts with the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoice-recurrences/{recurrence_public_id}/end": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "recurrence_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "endInvoiceRecurrence", "summary": "End a recurring invoice series", "description": "Requires sales:write and current owner/manager access; opting into automatic sending additionally requires invoices:send. Current rights and token allowlist are rechecked under locks. The stable public_id and expected_revision prevent stale or duplicate writes; no Idempotency-Key is needed for schedule management. Financial finalization and delivery retain their existing idempotent command contracts. Resuming after an intentional pause skips missed dates. Ending does not change existing drafts or invoices. Technical downtime creates missed occurrences as drafts only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceTransitionRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRecurrenceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Current state conflicts with the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/drafts": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listInvoiceDrafts", "summary": "List unfinalized invoice/credit concepts and quotations", "description": "Requires sales:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Cursor pagination; finalized documents remain available through the Sales API.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "invoice", "credit_note", "quote" ] } }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Cursor" } ] }, "post": { "operationId": "saveInvoiceDraft", "summary": "Save a nonfinancial incomplete draft or quotation", "description": "Requires sales:write and current owner/manager rights, rechecked under locks. No number, financial entry or mail is created. Identical current/immediately preceding revision input is safe to retry; changed stale input conflicts.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Command identity; nonfinancial retries follow the draft revision/content contract, not permanent financial replay.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveInvoiceDraftRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/drafts/{draft_public_id}": { "delete": { "operationId": "deleteInvoiceDraft", "summary": "Permanently delete an unissued invoice or credit-note draft", "description": "Requires sales:write, current owner/manager rights, API entitlement and token allowlist. Checks the current revision and active administration under locks. No draft tombstone, payload archive, invoice number or financial entry is created. Quotations and finalized draft pointers are not deletable here. Recurring series keep their independent template; a generated occurrence remains skipped without draft contents, preventing regeneration of that scheduled date. A repeated deletion returns 404 without writes. Stale edits with expected_revision >= 1 are refused. The existing revision-0 create contract is unchanged: replaying an original create can create a new non-financial draft after deletion; no permanent deleted-ID registry is retained.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "204": { "description": "Draft permanently deleted" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Draft revision or lifecycle conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "draft_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getInvoiceDraft", "summary": "Read a concept, quotation or finalized draft pointer", "description": "Requires sales:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. After finalization the document and presentation are null; sales_document_public_id identifies the financial source.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewQuote", "summary": "Calculate an unsaved quotation without financial posting", "description": "Requires sales:write and current owner/manager rights. No writes, saved draft, invoice number, journal, RC route or financial state hash. Current rights, token scope and tenant references are rechecked after any VIES evidence call. No Idempotency-Key is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotePreviewInput" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotePreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewIssuedInvoice", "summary": "Calculate the financial issuance preview", "description": "Requires sales:write and owner/manager rights. Uses the existing Sales planner without writes or numbering; supports issued_invoice/issued_credit_note only. This is not an incomplete-quote preview. For RC routes all participating administrations and rekening_courant:write are required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedInvoicePreviewInput" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/drafts/{draft_public_id}/finalize": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "draft_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "finalizeInvoice", "summary": "Assign the invoice number and post a saved draft atomically", "description": "Requires sales:write and current owner/manager rights. Customer name and country are required; customer street and city are optional. Issuer address and applicable tax requirements remain required. Current revision, fresh financial preview hash and required tax proof are checked under the existing locks. RC access covers every participant. Sending is never implicit. Same command returns the original result with Idempotency-Replayed; a later deleted source replays only the tombstone.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Permanent financial command replay; sending remains separate.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizeInvoiceRequest" } } } }, "responses": { "201": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentResponse" } } }, "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/{quote_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "quote_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getQuotation", "summary": "Read the saved quotation", "description": "Requires sales:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Incomplete quotations remain readable.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/{quote_public_id}/accept": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "quote_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "acceptQuotation", "summary": "Mark the quotation accepted", "description": "Requires sales:write and current owner/manager rights. Acceptance adds no financial entry and does not require invoice completeness. A meaningful later content change clears acceptance; a repeated acceptance at the current/immediately preceding accepted revision does not change it.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Command identity; nonfinancial retries follow the draft revision/content contract, not permanent financial replay.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRevisionRequest" } } } }, "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/{quote_public_id}/invoice-prefill": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "quote_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getQuotationInvoicePrefill", "summary": "Read invoice prefilling from a quotation", "description": "Requires sales:write and current owner/manager rights, like opening the web invoice creation form. Read-only: returns source revision/document/presentation, no new identity, automatic dates, saved draft, number or posting.", "responses": { "200": { "description": "Current result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteInvoicePrefillResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/{document_public_id}/pdf": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getInvoicePdf", "summary": "Download the current issued invoice or credit-note PDF", "description": "Requires sales:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Current token, entitlement, allowlist and actual access are rechecked under locks before copying coherent printable facts; rendering occurs after locks are released. No PDF archive or financial writes.", "responses": { "200": { "description": "Current PDF; not stored as an archive", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/{quote_public_id}/pdf": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "quote_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "downloadQuotationPdf", "summary": "Download the current quotation PDF", "description": "Requires sales:read, current actual tenant membership/ownership, API entitlement and token allowlist. Web support grants no API access. Current token, entitlement, allowlist and actual access are rechecked under locks before copying coherent printable facts; rendering occurs after locks are released. No PDF archive or financial writes. Requires the saved quote revision and printable quotation data, not an open fiscal year or revenue account. Applicable VIES verification occurs outside locks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRevisionRequest" } } } }, "responses": { "200": { "description": "Current PDF; not stored as an archive", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Revision, financial state, lifecycle or command conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/{quote_public_id}/delivery-options": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "quote_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getQuoteDeliveryOptions", "summary": "Read current quotation sending revisions and the editable recipient suggestion", "description": "Requires invoices:send and current owner/manager, tenant, entitlement and token-allowlist access. An incomplete quotation can be saved, but exporting requires named parties, dates, described/priced lines, currency and applicable VAT choices. No invoice number, full invoice addresses, revenue accounts or open financial year are required. This endpoint does not send mail or verify export completeness. A null settings revision means own SMTP has not been configured.", "responses": { "200": { "description": "Current sending options", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "expected_settings_revision", "to_address" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "expected_settings_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "to_address": { "type": [ "string", "null" ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/{quote_public_id}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "quote_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "requestQuoteDelivery", "summary": "Record one durable quotation sending request without financial posting", "description": "Requires invoices:send, not sales:write. Uses only the administration's own SMTP and the explicitly supplied recipient. Applicable tax evidence is verified before locks; sealed EU-B2B evidence is encrypted while pending and cleared at the terminal outcome. Before handoff, current permissions, printable quotation facts, VAT context and SMTP settings are rechecked. Acceptance alone does not change the document; changing printable content blocks the pending request. Replay returns status without resending; an uncertain outcome is never retried automatically. No invoice number, financial write, PDF archive or quote acceptance is created. HTTP 202 means recorded, not delivered.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryRequest" } } } }, "responses": { "202": { "description": "Sending request recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "200": { "description": "Existing request; not sent again", "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Quotation, SMTP settings, lifecycle or request key conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/quotes/{quote_public_id}/deliveries/{delivery_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "quote_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "delivery_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getQuoteDelivery", "summary": "Read a quotation sending outcome without sending again", "description": "Requires invoices:send and current tenant/token access. sent means SMTP server acceptance, not inbox delivery. The response contains no recipient, message, PDF, SMTP credentials, sealed VAT evidence or private workspace path.", "responses": { "200": { "description": "Current sending outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/{document_public_id}/delivery-options": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getInvoiceDeliveryOptions", "summary": "Read current sending revisions and the editable recipient suggestion", "description": "Requires invoices:send, current owner/manager access, an active administration, API entitlement and token allowlist. Only active issued invoices and credit notes are supported. No mail is sent. A null settings revision means invoice SMTP has not been configured. The client must explicitly supply its chosen to_address when requesting delivery; no contact-address fallback occurs.", "responses": { "200": { "description": "Current sending options", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "expected_settings_revision", "to_address" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "expected_settings_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "to_address": { "type": [ "string", "null" ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/{document_public_id}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "requestInvoiceDelivery", "summary": "Record one durable invoice sending request", "description": "Requires invoices:send, not sales:write. Current owner/manager access, active administration, API entitlement and token allowlist are checked again before SMTP handoff. The recipient is bound to this request and is not replaced after a contact edit. Document/printable facts and SMTP revisions are bound as well. No financial write or PDF archive is created. A changed request with the same key returns 409 idempotency_conflict; replay returns current status only and never sends again. An uncertain outcome is never retried automatically. HTTP 202 confirms recording, not mail delivery.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryRequest" } } } }, "responses": { "202": { "description": "Sending request recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "200": { "description": "Existing sending request; not sent again", "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Invoice, SMTP settings, lifecycle or request key conflicts with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/invoices/{document_public_id}/deliveries/{delivery_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "delivery_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getInvoiceDelivery", "summary": "Read a sending outcome without sending again", "description": "Requires invoices:send and actual tenant/token access. sent means SMTP server acceptance, not inbox delivery. Does not expose SMTP credentials, message content, recipient or private work paths. A deleted invoice retains only its redacted request status.", "responses": { "200": { "description": "Current sending outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/me": { "get": { "operationId": "getMe", "summary": "Return the authenticated user and token context", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Current API identity", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations": { "get": { "operationId": "listAdministrations", "summary": "List effectively accessible allowlisted administrations", "description": "Requires the administrations:read token ability. Results are ordered by public_id ascending and use a cursor containing public fields only.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned by links.next." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Accessible administrations", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdministrationCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/AbilityNotAllowed" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/contacts": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listContacts", "summary": "List administration contacts", "description": "Requires contacts:read. Defaults to active contacts and mutation-safe signed cursor pagination; stale cursors return validation_failed. BSN and notes are never selected or returned.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "default": "active" } }, { "name": "contact_type", "in": "query", "schema": { "type": "string", "enum": [ "person", "organization", "all" ], "default": "all" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact page", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createContact", "summary": "Create an administration contact", "description": "Requires contacts:write. Number allocation uses the administration high-water counter.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } } }, "responses": { "201": { "description": "Contact created", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/contacts/statistics": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getContactStatistics", "summary": "Return live administration contact statistics", "description": "Requires contacts:read. Values are derived by tenant-scoped SQL aggregation and are independent of contact-list filters.", "responses": { "200": { "description": "Contact statistics", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactStatisticsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/contacts/{contact_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/ContactPublicId" } ], "get": { "operationId": "showContact", "summary": "Return one contact with a masked BSN indicator", "description": "Requires contacts:read. Plaintext BSN is never returned.", "responses": { "200": { "description": "Contact", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "updateContact", "summary": "Partially update a contact", "description": "Requires contacts:write. Omitted fields retain their stored values. An empty BSN retains the stored value; remove_bsn explicitly clears it. Changing a person with a stored BSN to an organization requires remove_bsn=true; otherwise validation_failed is returned without a write. A semantic no-op creates no audit event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "responses": { "200": { "description": "Contact updated or unchanged", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteContact", "summary": "Delete an unused contact", "description": "Requires contacts:write. Relationship edges cascade; later business references restrict deletion.", "responses": { "204": { "description": "Contact deleted", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/contacts/{contact_public_id}/relationships": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/ContactPublicId" } ], "get": { "operationId": "listContactRelationships", "summary": "List relationships incident to one contact", "description": "Requires contacts:read.", "responses": { "200": { "description": "Contact relationships", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRelationshipCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/contact-relationships": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "createContactRelationship", "summary": "Create a canonical contact relationship", "description": "Requires contacts:write. Duplicate and symmetric inverse duplicate edges return 409.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRelationshipRequest" } } } }, "responses": { "201": { "description": "Relationship created", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRelationshipResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/contact-relationships/{contact_relationship_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/ContactRelationshipPublicId" } ], "delete": { "operationId": "deleteContactRelationship", "summary": "Delete one contact relationship", "description": "Requires contacts:write.", "responses": { "204": { "description": "Relationship deleted", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/relations": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listAdministrationRelations", "summary": "List shareholders, explicit representations and canonical administration links", "description": "Requires administration_relations:read. Counterpart administrations outside the token allowlist are redacted instead of disclosed.", "responses": { "200": { "description": "Administration relations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdministrationRelationsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/administrations/{administration_public_id}/shareholders": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "createAdministrationShareholder", "summary": "Link an existing contact as direct shareholder", "description": "Requires administration_relations:write. A new shareholder atomically gets a ready current-account setup in the administration currency, without a journal entry. Existing relationships are not reconfigured.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRelationRequest" } } } }, "responses": { "201": { "description": "Shareholder linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationMutationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/shareholders/{shareholder_public_id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "shareholder_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "deactivateAdministrationShareholder", "summary": "End shareholder status without clearing its current account", "description": "Requires administration_relations:write. Existing positions remain available for settlement. Legal forms without shareholders return validation error rc_legal_form_unsupported.", "responses": { "200": { "description": "Shareholder deactivated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationMutationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/contact-administration-links": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "createContactAdministrationLink", "summary": "Explicitly record that a contact represents another administration", "description": "Requires administration_relations:write and allowlisted write access to both administrations.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactAdministrationLinkRequest" } } } }, "responses": { "201": { "description": "Representation linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationMutationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/contact-administration-links/{link_public_id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "link_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "deactivateContactAdministrationLink", "summary": "End an explicit contact representation", "description": "Requires administration_relations:write and both administrations in the token allowlist; otherwise returns 404.", "responses": { "200": { "description": "Representation ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationMutationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/administrations/{administration_public_id}/administration-links": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "createAdministrationLink", "summary": "Create one canonical undirected administration link", "description": "Requires administration_relations:write and allowlisted write access to both administrations. New links atomically prepare separate current-account accounts at both ends. Equal accounting currencies use that currency; different currencies require denomination_currency_code. No exchange rate or financial entry is involved. Existing relationships are not reconfigured.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdministrationLinkRequest" } } } }, "responses": { "201": { "description": "Administrations linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationMutationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/administration-links/{link_public_id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "link_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "deactivateAdministrationLink", "summary": "End a canonical administration link", "description": "Requires administration_relations:write and both administrations in the token allowlist; otherwise returns 404.", "responses": { "200": { "description": "Administration link ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationMutationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/administrations/{administration_public_id}/rekening-courant/configurations": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listCurrentAccountConfigurations", "summary": "List local current-account configurations", "description": "Requires rekening_courant:read. Restricted counterpart identity is redacted.", "responses": { "200": { "description": "Current-account configurations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountConfigurationCollection" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/administrations/{administration_public_id}/rekening-courant/configuration": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "put": { "operationId": "putCurrentAccountConfiguration", "summary": "Create or replace explicit two-account position mappings", "description": "Requires rekening_courant:write and allowlisted write access to every position administration. The counterparty is a Contact or Administration, independent of its involvement role. Accounts are never created silently.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutCurrentAccountConfigurationRequest" } } } }, "responses": { "200": { "description": "Configuration saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountConfigurationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/configurations/{configuration_public_id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "configuration_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "deactivateCurrentAccountConfiguration", "summary": "Deactivate future route exposure while preserving balances", "description": "Requires rekening_courant:write and every position administration in the allowlist.", "responses": { "200": { "description": "Configuration deactivated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationMutationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/administrations/{administration_public_id}/rekening-courant/reachable-counterparties": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listReachableCurrentAccountCounterparties", "summary": "Return bounded cycle-safe reachable Contact terminals", "description": "Requires rekening_courant:read. Only Contacts that can be selected as transaction terminals are returned. Administration nodes remain internal route steps. Traversal is restricted to the token allowlist and bounded by configured hops, states, routes and configurations. Active routes have usage_mode normal. Ended relations are returned as settlement_only only while every affected position has a non-zero balance; they may reduce existing exposure but may not create exposure or cross zero.", "responses": { "200": { "description": "Reachable Contact terminals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountReachableCollection" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/configurations/{configuration_public_id}/reconciliation": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "configuration_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "get": { "operationId": "showCurrentAccountReconciliation", "summary": "Return live native current-account positions and their difference", "description": "Requires rekening_courant:read and every position administration in the allowlist. Manual ledger entries are included.", "responses": { "200": { "description": "Live reconciliation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountReconciliationResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/transactions": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listCurrentAccountTransactions", "summary": "List source-owned current-account transactions", "description": "Requires rekening_courant:read. Ordered by public ULID with a bounded opaque cursor. Route and target identifiers are redacted together when any route administration is outside the allowlist.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Current-account transaction page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountTransactionCollection" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "post": { "operationId": "postCurrentAccountTransaction", "summary": "Atomically post every administration journal entry in a selected route", "description": "Requires rekening_courant:write, Idempotency-Key and allowlisted write access to every administration receiving a journal entry. Inactive relations accept settlement toward zero only.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCurrentAccountTransactionRequest" } } } }, "responses": { "201": { "description": "Transaction posted with its immutable live plan snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountCommandTransactionResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/transactions/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewCurrentAccountTransaction", "summary": "Preview the route, position allocation and every generated journal entry", "description": "Requires rekening_courant:write. Multiple routes require explicit route_configuration_public_ids.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountTransactionInput" } } } }, "responses": { "200": { "description": "Transaction preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountPreviewResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/transactions/{transaction_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "showCurrentAccountTransaction", "summary": "Return one source-owned current-account transaction", "description": "Requires rekening_courant:read. Route and target identifiers outside the allowlist are redacted without disclosing names. Persisted routes do not claim a live usage_mode.", "responses": { "200": { "description": "Persisted current-account transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountPersistedTransactionResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateCurrentAccountTransaction", "summary": "Atomically correct all source-owned route journal entries", "description": "Requires rekening_courant:write, Idempotency-Key and unchanged administration endpoint set.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCurrentAccountTransactionRequest" } } } }, "responses": { "200": { "description": "Transaction updated with its immutable live plan snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountCommandTransactionResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/transactions/{transaction_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewCurrentAccountTransactionUpdate", "summary": "Preview an atomic current-account transaction correction", "description": "Requires rekening_courant:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewUpdateCurrentAccountTransactionRequest" } } } }, "responses": { "200": { "description": "Update preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountPreviewResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/transactions/{transaction_public_id}/delete": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "deleteCurrentAccountTransaction", "summary": "Atomically tombstone a current-account transaction and all owned journal entries", "description": "Requires rekening_courant:write and Idempotency-Key. Under the periodic currency method first obtain and confirm the deletion preview; the source and all existing valuation effects change atomically.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCurrentAccountTransactionRequest" } } } }, "responses": { "200": { "description": "Permanently redacted transaction tombstone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountDeletedTransactionResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/ledger-accounts": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listLedgerAccounts", "summary": "Return the complete chart of accounts sorted by code", "description": "Requires ledger_accounts:read.", "responses": { "200": { "description": "Complete chart of accounts", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccountCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createLedgerAccount", "summary": "Create a ledger account", "description": "Requires ledger_accounts:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLedgerAccountRequest" } } } }, "responses": { "201": { "description": "Ledger account created", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/ledger-accounts/{ledger_account_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/LedgerAccountPublicId" } ], "get": { "operationId": "showLedgerAccount", "summary": "Return one ledger account", "description": "Requires ledger_accounts:read.", "responses": { "200": { "description": "Ledger account", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "updateLedgerAccount", "summary": "Update a ledger account", "description": "Requires ledger_accounts:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLedgerAccountRequest" } } } }, "responses": { "200": { "description": "Ledger account updated", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteLedgerAccount", "summary": "Delete an unused ledger account", "description": "Requires ledger_accounts:write. Accounts linked to ledger data cannot be deleted.", "responses": { "204": { "description": "Ledger account deleted", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/ledger-accounts/{ledger_account_public_id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/LedgerAccountPublicId" } ], "post": { "operationId": "deactivateLedgerAccount", "summary": "Deactivate an active ledger account", "description": "Requires ledger_accounts:write.", "responses": { "200": { "description": "Ledger account deactivated", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/ledger-accounts/{ledger_account_public_id}/reactivate": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/LedgerAccountPublicId" } ], "post": { "operationId": "reactivateLedgerAccount", "summary": "Reactivate an inactive ledger account", "description": "Requires ledger_accounts:write.", "responses": { "200": { "description": "Ledger account reactivated", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/journal-entries": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listJournalEntries", "summary": "List manual journal entries newest number first", "description": "Requires journal_entries:read. Deleted tombstones are hidden unless status=deleted or status=all. The cursor is based on the public journal-entry number and contains no internal database ID.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned by links.next." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "posting_date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "posting_date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "posted", "no_difference", "deleted", "all" ], "default": "posted" } }, { "name": "ledger_account", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Ulid" }, "description": "Tenant-scoped ledger-account public ID. An unknown ID or an account from another administration returns ledger_account_not_found (404)." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Search description or a formatted J-number." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "number_desc", "date_asc", "date_desc" ], "default": "number_desc" }, "description": "Stable number or document/posting date order. Missing dates sort last; ties use entry number. Preserve filters when following cursors." } ], "responses": { "200": { "description": "Journal-entry page", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postJournalEntry", "summary": "Post a balanced manual journal entry", "description": "Requires journal_entries:write. Idempotent within the administration, API token, command and key scope. Currency scale and storage range are validated before idempotency lookup. If this completed command's target was later deleted, replay returns the redacted tombstone as 410 instead of a Post success response.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostJournalEntryRequest" } } } }, "responses": { "201": { "description": "Posted journal entry", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostedJournalEntryResponse" } } } }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/journal-entries/{journal_entry_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/JournalEntryPublicId" } ], "get": { "operationId": "showJournalEntry", "summary": "Return a journal entry or minimal deleted tombstone", "description": "Requires journal_entries:read.", "responses": { "200": { "description": "Journal-entry detail", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "editJournalEntry", "summary": "Replace the complete journal entry using optimistic concurrency", "description": "Requires journal_entries:write. A successful semantic no-op completes idempotency without changing revision or creating audit activity. If this completed command's target was later deleted, replay returns the redacted tombstone as 410 instead of an Edit success response.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditJournalEntryRequest" } } } }, "responses": { "200": { "description": "Posted journal entry after update or unchanged semantic no-op", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostedJournalEntryResponse" } } } }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/journal-entries/{journal_entry_public_id}/delete": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/JournalEntryPublicId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "deleteJournalEntry", "summary": "Delete financial data and retain a terminal journal-number tombstone", "description": "Requires journal_entries:write. This is intentionally POST /delete; no HTTP DELETE endpoint exists because expected_revision is required in the JSON body. Delete atomically redacts all completed Post/Edit/Delete result snapshots for this target to the minimal tombstone state; financial audit is then the only financial archive source.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteJournalEntryRequest" } } } }, "responses": { "200": { "description": "Minimal deleted tombstone", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedJournalEntryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/journal-entries/fx-preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewJournalEntryFx", "summary": "Preview FX conversion, carrying release and generated exchange-difference lines", "description": "Requires journal_entries:write. Read-only calculation: no journal, FX snapshot or audit row is persisted. Supply journal_entry_public_id when previewing an edit so the original financial order is used. Every supplied state_hash is verified by the subsequent journal command; carrying-dependent commands require it. Linked opening-item corrections additionally require purchases:write and always require the returned composite state_hash, including unlinking.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalFxPreviewRequest" } } } }, "responses": { "200": { "description": "Deterministic FX journal preview", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalFxPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fx-account-mappings": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "showFxAccountMappings", "summary": "Return realized and unrealized FX result-account mappings", "description": "Requires fx_revaluations:read.", "responses": { "200": { "description": "Current FX mappings", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxAccountMappingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateFxAccountMappings", "summary": "Replace FX result-account mappings with per-role optimistic revisions", "description": "Requires fx_revaluations:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutFxAccountMappingsRequest" } } } }, "responses": { "200": { "description": "Updated FX mappings", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxAccountMappingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/fx-revaluations": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "get": { "operationId": "listFxRevaluations", "summary": "List posted revaluations, preserved zero-difference controls and deleted revaluations with a signed public-ULID keyset cursor", "description": "Requires fx_revaluations:read. A no_difference control retains rates and position evidence but has no financial posting: journal_entry is null. It remains correctable in an open fiscal year.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "posted", "no_difference", "deleted", "all" ], "default": "all" } } ], "responses": { "200": { "description": "FX revaluation page", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postFxRevaluation", "summary": "Post an FX revaluation and its balanced journal entry", "description": "Requires fx_revaluations:write and Idempotency-Key. Fresh preview hashes are mandatory.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostFxRevaluationRequest" } } } }, "responses": { "201": { "description": "Posted revaluation", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/FxStateConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/fx-revaluations/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "post": { "operationId": "previewFxRevaluation", "summary": "Preview monetary positions and revaluation differences without mutation", "description": "Requires fx_revaluations:write. Pass revaluation_public_id only when preparing an update; its current generated journal is excluded from the position hash.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewFxRevaluationRequest" } } } }, "responses": { "200": { "description": "Deterministic revaluation preview", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/FxStateConflict" }, "422": { "description": "Validation error or an explicit same-day revaluation placement is required.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/FxRevaluationOrderRequired" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/fx-revaluations/{revaluation_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" }, { "$ref": "#/components/parameters/RevaluationPublicId" } ], "get": { "operationId": "showFxRevaluation", "summary": "Return one posted or deleted FX revaluation", "description": "Requires fx_revaluations:read.", "responses": { "200": { "description": "FX revaluation", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateFxRevaluation", "summary": "Replace a posted FX revaluation using optimistic concurrency", "description": "Requires fx_revaluations:write and Idempotency-Key. Fresh preview hashes and expected_revision are mandatory.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFxRevaluationRequest" } } } }, "responses": { "200": { "description": "Updated revaluation", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/FxStateConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/fx-revaluations/{revaluation_public_id}/delete": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" }, { "$ref": "#/components/parameters/RevaluationPublicId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "deleteFxRevaluation", "summary": "Delete a revaluation, reverse its generated journal and retain a tombstone", "description": "Requires fx_revaluations:write. Idempotent replays return only the tombstone-safe result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFxRevaluationRequest" } } } }, "responses": { "200": { "description": "Deleted revaluation tombstone", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listFiscalYears", "summary": "Return the complete chronological fiscal calendar without pagination", "description": "Requires fiscal_years:read.", "responses": { "200": { "description": "Complete fiscal calendar", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYearCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createNextFiscalYear", "summary": "Create the next contiguous fiscal year", "description": "Requires fiscal_years:write. starts_on is determined by the server. One read-only proposal and confirmation cover dates and existing monthly/annual journals. An unused future year needs no additional financial input. Only fiscal_years:write is required; consequential Broker writes do not require investments:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFiscalYearRequest" } } } }, "responses": { "201": { "description": "Fiscal year created", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYearResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "200": { "description": "Read-only financial proposal or missing-facts result; nothing has been written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalCalendarPreviewResponse" } } } } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "get": { "operationId": "showFiscalYear", "summary": "Return one fiscal year", "description": "Requires fiscal_years:read.", "responses": { "200": { "description": "Fiscal year", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYearResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "updateFiscalYear", "summary": "Update fiscal-year dates without changing adjacent years", "description": "Requires fiscal_years:write. status cannot be changed here. One read-only proposal and confirmation cover dates and existing monthly/annual journals. An unused future year needs no additional financial input. Only fiscal_years:write is required; consequential Broker writes do not require investments:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFiscalYearRequest" } } } }, "responses": { "200": { "description": "Fiscal year updated Or a read-only proposal/missing-facts result requiring another request.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalYearResponse" }, { "$ref": "#/components/schemas/FiscalCalendarPreviewResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteFiscalYear", "summary": "Delete an eligible open edge fiscal year", "description": "Requires fiscal_years:write. One read-only proposal and confirmation cover dates and existing monthly/annual journals. An unused future year needs no additional financial input. Only fiscal_years:write is required; consequential Broker writes do not require investments:write.", "responses": { "204": { "description": "Fiscal year deleted", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "200": { "description": "Read-only financial proposal or missing-facts result; nothing has been written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalCalendarPreviewResponse" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalCalendarRemovalRequest" } } } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/adjust-boundary": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "post": { "operationId": "adjustFiscalYearBoundary", "summary": "Atomically move the boundary with the directly following open fiscal year", "description": "Requires fiscal_years:write. One read-only proposal and confirmation cover dates and existing monthly/annual journals. An unused future year needs no additional financial input. Only fiscal_years:write is required; consequential Broker writes do not require investments:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustBoundaryRequest" } } } }, "responses": { "200": { "description": "Both affected fiscal years Or a read-only proposal/missing-facts result requiring another request.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BoundaryResponse" }, { "$ref": "#/components/schemas/FiscalCalendarPreviewResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/close": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "post": { "operationId": "closeFiscalYear", "summary": "Close the oldest open fiscal year after its end date", "description": "Requires fiscal_years:write. The server recalculates the full-year result and financial-position reconciliation under the close lock and returns fiscal_year_closing_unbalanced (409) for a non-zero difference. Closing creates no financial entry or result allocation. Reopen is intentionally not exposed through the API.", "responses": { "200": { "description": "Fiscal year closed", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYearResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/closing-preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "get": { "operationId": "showFiscalYearClosingPreview", "summary": "Return the derived fiscal-year result and closing check", "description": "Requires both fiscal_years:read and general_ledger:read. The preview is read-only, creates no audit event or financial entry, and uses active journal lines plus opening-balance lines without stored result balances. close_eligible expresses business eligibility only and does not grant close permission. Broker position reconciliation uses the selected reporting cutoff and keeps long holdings and short liabilities separate. At fiscal year-end, missing or superseded position valuations prevent closing. The broker check concerns entered data only and does not require or verify an external statement. The close command rechecks the same conditions under its administration lock.", "responses": { "200": { "description": "Derived closing preview", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYearClosingPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/general-ledger": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" }, { "$ref": "#/components/parameters/LedgerDateFrom" }, { "$ref": "#/components/parameters/LedgerDateTo" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" } ], "get": { "operationId": "listGeneralLedger", "summary": "Return computed account balances for one fiscal year", "description": "Requires general_ledger:read. No balances are stored. Balance-sheet accounts carry the first opening balance and all active prior-year journal lines forward; profit-and-loss accounts reset at each fiscal-year start. Deleted journal-entry tombstones are excluded.", "parameters": [ { "name": "include_empty", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Keyset-paginated computed general ledger", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralLedgerResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/general-ledger/{ledger_account_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" }, { "$ref": "#/components/parameters/LedgerAccountPublicId" }, { "$ref": "#/components/parameters/LedgerDateFrom" }, { "$ref": "#/components/parameters/LedgerDateTo" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" } ], "get": { "operationId": "showGeneralLedgerCard", "summary": "Return a computed ledger card for one account and fiscal year", "description": "Requires general_ledger:read. Lines remain separate and use signed keyset continuation ordered by posting date, entry number and line number. On each page, beginning_balance is the exact balance immediately before that page. Balance-sheet accounts include prior-year carryforward; profit-and-loss accounts start each fiscal year at zero.", "responses": { "200": { "description": "Keyset-paginated ledger card", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralLedgerCardResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/reports/trial-balance": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" }, { "$ref": "#/components/parameters/ReportDateFrom" }, { "$ref": "#/components/parameters/ReportDateTo" }, { "$ref": "#/components/parameters/ReportIncludeZero" } ], "get": { "operationId": "showTrialBalance", "summary": "Return the computed trial balance", "description": "Requires financial_reports:read. Returns beginning, period movement and closing debit/credit columns. Balance accounts carry forward; profit-and-loss accounts reset at the fiscal-year start. Prior-year result is a derived, non-bookable row. No closing entry or stored result balance is created.", "responses": { "200": { "description": "Computed trial balance", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialBalanceReportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/reports/balance-sheet": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" }, { "$ref": "#/components/parameters/ReportAsOf" }, { "$ref": "#/components/parameters/ReportIncludeZero" } ], "get": { "operationId": "showBalanceSheet", "summary": "Return the computed balance sheet", "description": "Requires financial_reports:read. Presents physical balance accounts under assets or liabilities and equity at the inclusive as-of date. Prior-year and current-year results are derived rows under equity. totals.difference and technical_reconciliation expose inconsistencies without creating an automatic correction.", "responses": { "200": { "description": "Computed balance sheet", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSheetReportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/reports/profit-and-loss": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" }, { "$ref": "#/components/parameters/ReportDateFrom" }, { "$ref": "#/components/parameters/ReportDateTo" }, { "$ref": "#/components/parameters/ReportIncludeZero" } ], "get": { "operationId": "showProfitAndLoss", "summary": "Return the computed profit and loss statement", "description": "Requires financial_reports:read. Returns exact debit, credit, signed, display and result-effect amounts for the inclusive period. The result is derived from active journal lines only and is never stored as a balance or financial entry.", "responses": { "200": { "description": "Computed profit and loss statement", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfitAndLossReportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/opening-balance": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "get": { "operationId": "showOpeningBalance", "summary": "Return the existing opening balance", "description": "Requires opening_balances:read. A fiscal year for which no opening balance exists, including after clear, returns opening_balance_not_found (404).", "responses": { "200": { "description": "Existing opening balance", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/OpeningBalanceNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putOpeningBalance", "summary": "Create, fully replace, leave unchanged or clear the opening balance", "description": "Requires opening_balances:write and Idempotency-Key. Only the first chronological open fiscal year is eligible. An empty lines array physically clears the operational opening balance while financial audit remains subject to its retention period. First obtain state_hash from the read-only preview. Confirmation preserves the original opening values and atomically includes effects on existing currency valuations; later ordinary cash transactions are retained.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutOpeningBalanceRequest" } } } }, "responses": { "200": { "description": "Updated, unchanged or cleared opening balance", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceCommandResponse" } } } }, "201": { "description": "Opening balance created", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/vat-treatments": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "direction", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sale", "purchase", "adjustment" ] } }, { "name": "on", "in": "query", "required": true, "description": "Effective VAT date. Dates before 2022-01-01 fail closed.", "schema": { "type": "string", "format": "date", "examples": [ "2022-01-01" ] } } ], "get": { "operationId": "listVatTreatments", "summary": "Return the effective localized VAT treatment catalog", "description": "Requires vat_treatments:read. This is the only public VAT operation; it performs no calculation and exposes no numeric database identifiers.", "responses": { "200": { "description": "Effective VAT treatments in fiscal display order", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatTreatmentCatalogResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listSalesDocuments", "summary": "List sales documents with live status", "description": "Requires sales:read.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "status", "in": "query", "description": "Defaults to posted.", "schema": { "type": "string", "enum": [ "posted", "deleted", "all" ], "default": "posted" } }, { "name": "ledger_account", "in": "query", "required": false, "description": "Filter by a source ledger account public ID belonging to this administration, including explicit balance-settlement source accounts. Returns complete documents once, preserving full document totals. Automatic counterpart accounts do not match merely because of their posting role.", "schema": { "type": "string", "format": "ulid", "nullable": true } }, { "name": "q", "in": "query", "description": "Literal search in customer names, document number and description.", "schema": { "type": "string", "maxLength": 255, "nullable": true } }, { "name": "invoice_date_from", "in": "query", "description": "Inclusive invoice-date lower bound.", "schema": { "type": "string", "format": "date", "nullable": true } }, { "name": "invoice_date_to", "in": "query", "description": "Inclusive invoice-date upper bound, on or after invoice_date_from if supplied.", "schema": { "type": "string", "format": "date", "nullable": true } }, { "name": "payment_status", "in": "query", "description": "Existing sales status: outstanding open/partially_paid, or paid. Credit and written-off statuses remain under all.", "schema": { "type": "string", "enum": [ "all", "open", "paid" ], "default": "all" } }, { "name": "sort", "in": "query", "description": "Explicit invoice-date order; missing dates last, unique ID tie-breaker. Without this parameter the existing public-ID descending API order is preserved.", "schema": { "type": "string", "enum": [ "date_desc", "date_asc" ] } } ], "responses": { "200": { "description": "List sales documents with live status", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postSalesDocument", "summary": "Post a sales document atomically", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSalesDocumentRequest" } } } }, "responses": { "201": { "description": "Post a sales document atomically", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewSalesDocument", "summary": "Preview a sales document", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentInput" } } } }, "responses": { "200": { "description": "Preview a sales document", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getSalesDocument", "summary": "Get a sales document and managed children", "description": "Requires sales:read. The public ID always identifies the same Sales document. A terminal tombstone is returned at the same URL.", "parameters": [], "responses": { "200": { "description": "Get a sales document and managed children", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateSalesDocument", "summary": "Update a sales document", "description": "Requires sales:write. Metadata and financial facts are updated on the same Sales document and existing Journal identities in an open fiscal year. Deterministic dependent receipts, refunds and credit notes are rebuilt atomically from the same read-only plan used by preview; an ambiguous fiscal, FX or route choice fails before any write. Increasing only the amount of a previously paid document preserves actual receipt amounts and existing payment-difference amounts: only the added amount remains open, with no automatic extra receipt or write-off. The state hash covers the dependent plans and is rechecked under lock. An explicitly changed tax basis recalculates derived credit VAT and receivable/refund splits through the existing central rules; it does not alter actual receipt or refund amounts. The document type is immutable. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSalesDocumentRequest" } } } }, "responses": { "200": { "description": "Update a sales document", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSalesDocumentUpdate", "summary": "Preview a sales document update", "description": "Requires sales:write. Read-only preview: no financial facts, audit records or command reservations are written. The preview reports in_place_update or no_change and lists every dependent header and Journal identity that will be rebuilt in place. Its state hash covers the projected dependent receipts, refunds and credit notes; update rechecks the same plan under lock. Increasing only the amount of a previously paid document preserves actual receipts and existing payment-difference amounts and leaves only the added amount open. An explicitly changed tax basis recalculates derived credit VAT and receivable/refund splits through the existing central rules; it does not alter actual receipt or refund amounts. The document type is immutable. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSalesDocumentPreviewRequest" } } } }, "responses": { "200": { "description": "Preview a sales document update", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/delete": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "deleteSalesDocument", "summary": "Delete a sales document to a terminal tombstone", "description": "Requires sales:write. Requires the state_hash returned by delete-preview. The same Sales and Journal headers become terminal tombstones; derived financial facts are removed without reversal or replacement records. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSalesDocumentRequest" } } } }, "responses": { "200": { "description": "Delete a sales document to a terminal tombstone", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/delete-preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewDeleteSalesDocument", "summary": "Preview the complete Sales-document delete graph", "description": "Requires sales:write. Read-only. Returns every document, settlement and retained J-number that the single atomic tombstone action affects, plus the required state_hash.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewDeleteSalesDocumentRequest" } } } }, "responses": { "200": { "description": "Preview the complete delete graph", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDeletePreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/credit-notes/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewExternalSalesCreditNote", "summary": "Preview an external credit note", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditNoteInput" } } } }, "responses": { "200": { "description": "Preview an external credit note", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/credit-notes": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "postExternalSalesCreditNote", "summary": "Post an external credit note", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSalesCreditNoteRequest" } } } }, "responses": { "201": { "description": "Post an external credit note", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/receipts/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSalesReceipt", "summary": "Preview a sales receipt", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementInput" } } } }, "responses": { "200": { "description": "Preview a sales receipt", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/receipts": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "postSalesReceipt", "summary": "Post a sales receipt", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSalesSettlementRequest" } } } }, "responses": { "201": { "description": "Post a sales receipt", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/refunds/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSalesRefund", "summary": "Preview a sales refund", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementInput" } } } }, "responses": { "200": { "description": "Preview a sales refund", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/refunds": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "postSalesRefund", "summary": "Post a sales refund", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSalesSettlementRequest" } } } }, "responses": { "201": { "description": "Post a sales refund", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/customer-credits": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listSalesCustomerCredits", "summary": "List open customer credits", "description": "Requires sales:read. Customer credit is a liability and has no revenue or VAT effect.", "responses": { "200": { "description": "List open customer credits", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerCreditCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/customer-credits/{sales_customer_credit_public_id}/refunds/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_customer_credit_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSalesCustomerCreditRefund", "summary": "Preview a customer-credit refund", "description": "Requires sales:write. The refund reduces the customer-credit liability and never changes revenue or VAT. Cross-administration routes additionally require rekening_courant:write and access to every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerCreditRefundInput" } } } }, "responses": { "200": { "description": "Preview a customer-credit refund", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/customer-credits/{sales_customer_credit_public_id}/refunds": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_customer_credit_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "postSalesCustomerCreditRefund", "summary": "Post a customer-credit refund", "description": "Requires sales:write. The command is idempotent, reduces the liability and preserves FX evidence without a VAT effect. Cross-administration routes additionally require rekening_courant:write and access to every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSalesCustomerCreditRefundRequest" } } } }, "responses": { "201": { "description": "Post a customer-credit refund", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/settlements": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listSalesSettlements", "summary": "List receipts and refunds", "description": "Requires sales:read.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "status", "in": "query", "description": "Defaults to posted.", "schema": { "type": "string", "enum": [ "posted", "deleted", "all" ], "default": "posted" } } ], "responses": { "200": { "description": "List receipts and refunds", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/settlements/{sales_settlement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSalesSettlementUpdate", "summary": "Preview a receipt or refund update", "description": "Requires sales:write. Preview and commit address the same settlement public ID and existing Journal identities. Derived allocations, FX, VAT, customer-credit and provenance facts are rebuilt atomically. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementUpdatePreviewCommand" } } } }, "responses": { "200": { "description": "Preview a receipt or refund update", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementUpdatePreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/settlements/{sales_settlement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "put": { "operationId": "updateSalesSettlement", "summary": "Update a receipt or refund in place", "description": "Requires sales:write. Updates the same settlement and Journal headers using the state_hash from preview. Derived allocations, FX, VAT, customer-credit and provenance facts are rebuilt atomically. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementUpdateCommand" } } } }, "responses": { "200": { "description": "Update the same receipt or refund identity and retained J-numbers", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/settlements/{sales_settlement_public_id}/delete": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "deleteSalesSettlement", "summary": "Delete a receipt or refund to a terminal tombstone", "description": "Requires sales:write. Requires the state_hash returned by delete-preview. The same settlement and Journal headers become terminal tombstones and dependent customer-credit facts are removed atomically without reversal or replacement records. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSalesSourceRequest" } } } }, "responses": { "200": { "description": "Delete the same receipt or refund to a minimal terminal tombstone", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementTombstoneResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/settlements/{sales_settlement_public_id}/delete-preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewDeleteSalesSettlement", "summary": "Preview the complete Sales-settlement delete graph", "description": "Requires sales:write. Read-only. Returns every dependent settlement and retained J-number affected by the single atomic tombstone action, plus the required state_hash.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewDeleteSalesSourceRequest" } } } }, "responses": { "200": { "description": "Preview the complete delete graph", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementDeletePreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/options": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getSalesOptions", "summary": "Get safe sales contact and account options", "description": "Requires both sales:read and contacts:read.", "parameters": [ { "name": "region", "in": "query", "schema": { "type": "string", "enum": [ "nl", "eu", "non_eu" ] } }, { "name": "supply_type", "in": "query", "schema": { "type": "string", "enum": [ "goods", "services", "digital_services" ] } }, { "name": "customer_type", "in": "query", "schema": { "type": "string", "enum": [ "b2b", "b2c" ] } }, { "name": "margin_method", "in": "query", "schema": { "type": "string", "enum": [ "none", "individual", "globalisation" ] } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Get safe sales contact and account options", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOptionsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/reconciliation": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getSalesReconciliation", "summary": "Reconcile live customer open items to trade receivables", "description": "Requires sales:read.", "parameters": [], "responses": { "200": { "description": "Reconcile live customer open items to trade receivables", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesReconciliationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/account-mappings": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getSalesAccountMappings", "summary": "Get semantic sales control-account mappings", "description": "Requires sales:read.", "parameters": [], "responses": { "200": { "description": "Get semantic sales control-account mappings", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesAccountMappingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putSalesAccountMappings", "summary": "Set semantic sales control-account mappings", "description": "Requires sales:write. Cross-administration routes additionally require rekening_courant:write and an allowlist entry for every affected administration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSalesAccountMappingsRequest" } } } }, "responses": { "200": { "description": "Set semantic sales control-account mappings", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesAccountMappingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/purchases/documents": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listPurchaseDocuments", "summary": "List purchase documents", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "deleted", "all" ], "default": "active" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Search supplier name, invoice reference, description or exact I-number; wildcards are literal." }, { "name": "document_date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive invoice date from." }, { "name": "document_date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive invoice date to; on or after from when both are supplied." }, { "name": "payment_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "open", "paid" ], "default": "all" }, "description": "Existing payment status: credits and deleted documents appear only with all." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "number_desc", "date_asc", "date_desc" ], "default": "date_desc" }, "description": "Stable number or document/posting date order. Missing dates sort last; ties use entry number. Preserve filters when following cursors." }, { "name": "ledger_account", "in": "query", "required": false, "description": "Filter by a source ledger account public ID belonging to this administration. Returns complete documents once, preserving full document totals; includes purchase payroll cost accounts. Automatic counterpart accounts do not match merely because of their posting role.", "schema": { "type": "string", "format": "ulid", "nullable": true } } ], "responses": { "200": { "description": "Purchase documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDocumentCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" } } }, "post": { "operationId": "postPurchaseDocument", "summary": "Post a purchase document", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPurchaseDocumentRequest" } } } }, "responses": { "201": { "description": "Posted document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDocumentResponse" } } } }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/purchases/documents/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewPurchaseDocument", "summary": "Preview a purchase document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewPurchaseDocumentRequest" } } } }, "responses": { "200": { "description": "Deterministic purchase plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePreview" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/purchases/documents/{purchase_document_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getPurchaseDocument", "summary": "Get a purchase document, including a safe tombstone", "responses": { "200": { "description": "Purchase document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDocumentResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updatePurchaseDocument", "summary": "Update the same purchase document in place", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePurchaseDocumentRequest" } } } }, "responses": { "200": { "description": "Updated document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDocumentResponse" } } } }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/purchases/documents/{purchase_document_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewPurchaseDocumentUpdate", "summary": "Preview an in-place purchase update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewUpdatePurchaseDocumentRequest" } } } }, "responses": { "200": { "description": "Deterministic update plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePreview" } } } }, "409": { "$ref": "#/components/responses/BusinessConflict" } } } }, "/administrations/{administration_public_id}/purchases/documents/{purchase_document_public_id}/delete": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "deletePurchaseDocument", "summary": "Logically delete a purchase document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePurchaseSourceRequest" } } } }, "responses": { "200": { "description": "Minimal tombstone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDocumentResponse" } } } }, "409": { "$ref": "#/components/responses/BusinessConflict" } } } }, "/administrations/{administration_public_id}/purchases/settlements": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listPurchaseSettlements", "summary": "List purchase payments and other settlement events", "responses": { "200": { "description": "Purchase settlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementCollection" } } } } } }, "post": { "operationId": "postPurchaseSettlement", "summary": "Post a payment with explicit allocations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPurchaseSettlementRequest" } } } }, "responses": { "201": { "description": "Posted payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/purchases/settlements/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewPurchaseSettlement", "summary": "Preview a payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewPurchaseSettlementRequest" } } } }, "responses": { "200": { "description": "Settlement plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/settlements/{purchase_settlement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getPurchaseSettlement", "summary": "Get a purchase settlement, including a safe tombstone", "responses": { "200": { "description": "Purchase settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updatePurchaseSettlement", "summary": "Update the same payment in place", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePurchaseSettlementRequest" } } } }, "responses": { "200": { "description": "Updated settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } }, "409": { "$ref": "#/components/responses/BusinessConflict" } } } }, "/administrations/{administration_public_id}/purchases/settlements/{purchase_settlement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewPurchaseSettlementUpdate", "summary": "Preview a settlement update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewUpdatePurchaseSettlementRequest" } } } }, "responses": { "200": { "description": "Settlement plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/settlements/{purchase_settlement_public_id}/delete": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "deletePurchaseSettlement", "summary": "Logically delete an independent purchase settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePurchaseSourceRequest" } } } }, "responses": { "200": { "description": "Minimal tombstone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } }, "409": { "$ref": "#/components/responses/BusinessConflict" } } } }, "/administrations/{administration_public_id}/purchases/supplier-credits": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listSupplierCredits", "summary": "List available supplier credits", "responses": { "200": { "description": "Supplier credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditCollection" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-refunds": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "postSupplierRefund", "summary": "Post a supplier refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierRefundRequest" } } } }, "responses": { "201": { "description": "Supplier refund", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-refunds/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewSupplierRefund", "summary": "Preview a supplier refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewSupplierRefundRequest" } } } }, "responses": { "200": { "description": "Refund plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-refunds/{purchase_settlement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "put": { "operationId": "updateSupplierRefund", "summary": "Update the same supplier refund in place", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSupplierRefundRequest" } } } }, "responses": { "200": { "description": "Updated refund", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-refunds/{purchase_settlement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSupplierRefundUpdate", "summary": "Preview a supplier-refund update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewUpdateSupplierRefundRequest" } } } }, "responses": { "200": { "description": "Refund plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-credit-applications": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "postSupplierCreditApplication", "summary": "Apply a supplier credit explicitly", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSupplierCreditApplicationRequest" } } } }, "responses": { "201": { "description": "Supplier-credit application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-credit-applications/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewSupplierCreditApplication", "summary": "Preview a supplier-credit application", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewSupplierCreditApplicationRequest" } } } }, "responses": { "200": { "description": "Application plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-credit-applications/{purchase_settlement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "put": { "operationId": "updateSupplierCreditApplication", "summary": "Update the same supplier-credit application in place", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSupplierCreditApplicationRequest" } } } }, "responses": { "200": { "description": "Updated application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/supplier-credit-applications/{purchase_settlement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewSupplierCreditApplicationUpdate", "summary": "Preview a supplier-credit application update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewUpdateSupplierCreditApplicationRequest" } } } }, "responses": { "200": { "description": "Application plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementPreview" } } } } } } }, "/administrations/{administration_public_id}/purchases/vat-corrections": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listPurchaseVatCorrections", "summary": "List purchase VAT corrections", "responses": { "200": { "description": "VAT corrections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseVatCorrectionCollection" } } } } } }, "post": { "operationId": "postPurchaseVatCorrection", "summary": "Post an explicit unpaid-VAT correction", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPurchaseVatCorrectionRequest" } } } }, "responses": { "201": { "description": "VAT correction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseVatCorrectionResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/vat-corrections/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewPurchaseVatCorrection", "summary": "Preview an unpaid-VAT correction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewPurchaseVatCorrectionRequest" } } } }, "responses": { "200": { "description": "VAT-correction plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseVatCorrectionPreviewResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/vat-renewals": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "postPurchaseVatRenewal", "summary": "Renew VAT deduction after payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPurchaseVatRenewalRequest" } } } }, "responses": { "201": { "description": "Renewed deduction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseVatCorrectionResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/vat-renewals/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewPurchaseVatRenewal", "summary": "Preview renewed VAT deduction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewPurchaseVatRenewalRequest" } } } }, "responses": { "200": { "description": "Renewal plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseVatCorrectionPreviewResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/open-items": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listPurchaseOpenItems", "summary": "List current or historical supplier open items", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "supplier_public_id", "in": "query", "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Derived open items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOpenItemCollection" } } } } } } }, "/administrations/{administration_public_id}/purchases/one-year-review": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "reviewPurchaseVatOneYear", "summary": "List one-year VAT reminder candidates without writing", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Reminder candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOpenItemCollection" } } } } } } }, "/administrations/{administration_public_id}/purchases/reconciliation": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "reconcilePurchases", "summary": "Reconcile derived supplier open items to trade payables", "responses": { "200": { "description": "Purchase reconciliation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReconciliationResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/options": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getPurchaseOptions", "summary": "Get tenant-scoped public Purchase options", "responses": { "200": { "description": "Purchase options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOptionsResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/account-mappings": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getPurchaseAccountMappings", "summary": "Get Purchase account mappings", "responses": { "200": { "description": "Mappings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseAccountMappingsResponse" } } } } } }, "put": { "operationId": "putPurchaseAccountMappings", "summary": "Set all Purchase account mappings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutPurchaseAccountMappingsRequest" } } } }, "responses": { "200": { "description": "Mappings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseAccountMappingsResponse" } } } } } } }, "/administrations/{administration_public_id}/purchases/contacts/{contact_public_id}/financial-overview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/ContactPublicId" } ], "get": { "operationId": "getContactFinancialOverview", "summary": "Get the read-only joint Sales and Purchase contact projection", "responses": { "200": { "description": "Financial contact overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFinancialOverviewResponse" } } } } } } }, "/administrations/{administration_public_id}/broker/currency-exchanges": { "get": { "tags": [ "Broker" ], "summary": "List currency exchanges", "description": "Requires investments:read and current view permission. Token administration allowlist and current tenant membership apply. Unknown query/body fields are rejected. Existing Bank accounts and the shared monetary journal system are used. Only page is accepted as a query parameter; no request body.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Active sources, 25 per page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeListResponse" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source or account not found in this administration." }, "409": { "description": "Command key conflict or financial dependency/state conflict." }, "422": { "description": "Invalid input, stale proposal, unavailable binding or account, or unsupported financial state. No partial posting." } } } }, "/administrations/{administration_public_id}/broker/currency-exchanges/{public_id}": { "get": { "tags": [ "Broker" ], "summary": "Read the current currency exchange", "description": "Requires investments:read and current view permission. Token administration allowlist and current tenant membership apply. Unknown query/body fields are rejected. No query parameters are accepted. Existing Bank accounts and the shared monetary journal system are used. No request body. Removed sources return a safe tombstone.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeResponse" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source or account not found in this administration." }, "409": { "description": "Command key conflict or financial dependency/state conflict." }, "422": { "description": "Invalid input, stale proposal, unavailable binding or account, or unsupported financial state. No partial posting." } } } }, "/administrations/{administration_public_id}/broker/currency-exchanges/preview": { "post": { "tags": [ "Broker" ], "summary": "Preview a new currency exchange", "description": "Requires investments:write and current update permission for every affected administration. Token administration allowlist and current tenant membership apply. Unknown query/body fields are rejected. No query parameters are accepted. Existing Bank accounts and the shared monetary journal system are used.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangePreviewResponse" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source or account not found in this administration." }, "409": { "description": "Command key conflict or financial dependency/state conflict." }, "422": { "description": "Validation failure, or an explicit same-day placement is required. The special placement response has the documented top-level errors and day_order_options; ordinary validation uses the standard API error response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyExchangeOrderRequired" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeInput" } } } } } }, "/administrations/{administration_public_id}/broker/currency-exchanges/{public_id}/preview": { "post": { "tags": [ "Broker" ], "summary": "Preview correction of a currency exchange", "description": "Requires investments:write and current update permission for every affected administration. Token administration allowlist and current tenant membership apply. Unknown query/body fields are rejected. No query parameters are accepted. Existing Bank accounts and the shared monetary journal system are used.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangePreviewResponse" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source or account not found in this administration." }, "409": { "description": "Command key conflict or financial dependency/state conflict." }, "422": { "description": "Validation failure, or an explicit same-day placement is required. The special placement response has the documented top-level errors and day_order_options; ordinary validation uses the standard API error response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyExchangeOrderRequired" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeInput" } } } } } }, "/administrations/{administration_public_id}/broker/currency-exchanges/{public_id}/removal-preview": { "post": { "tags": [ "Broker" ], "summary": "Preview removal of a currency exchange", "description": "Requires investments:write and current update permission for every affected administration. Token administration allowlist and current tenant membership apply. Unknown query/body fields are rejected. No query parameters are accepted. Existing Bank accounts and the shared monetary journal system are used. The request body must be empty. Existing Bank links must first be explicitly unlinked; changes to closed financial periods are rejected. The preview includes removed journals and all dependent changes.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangePreviewResponse" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source or account not found in this administration." }, "409": { "description": "Command key conflict or financial dependency/state conflict." }, "422": { "description": "Validation failure, or an explicit same-day placement is required. The special placement response has the documented top-level errors and day_order_options; ordinary validation uses the standard API error response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyExchangeOrderRequired" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } } } } }, "/administrations/{administration_public_id}/broker/currency-exchanges/confirm": { "post": { "tags": [ "Broker" ], "summary": "Confirm a reviewed currency exchange command", "description": "Requires investments:write and current update permission for every affected administration. Token administration allowlist and current tenant membership apply. Unknown query/body fields are rejected. No query parameters are accepted. Existing Bank accounts and the shared monetary journal system are used. Use the same Idempotency-Key and principal as preview. Source creation, correction, removal and dependent replay are atomic. A replay returns current source state; an old create/update receipt whose source was subsequently removed returns HTTP 410 without stale amounts.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeResponse" } } }, "headers": { "Idempotent-Replay": { "description": "Whether this is a replay of a completed command.", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source or account not found in this administration." }, "409": { "description": "Command key conflict or financial dependency/state conflict." }, "422": { "description": "Invalid input, stale proposal, unavailable binding or account, or unsupported financial state. No partial posting." }, "201": { "description": "New source created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeResponse" } } }, "headers": { "Idempotent-Replay": { "description": "Whether this is a replay of a completed command.", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "410": { "description": "The source of a previously completed create/update command has since been removed; safe current tombstone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeResponse" } } }, "headers": { "Idempotent-Replay": { "description": "Whether this is a replay of a completed command.", "schema": { "type": "string", "enum": [ "true", "false" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyExchangeConfirmInput" } } } } } }, "/administrations/{administration_public_id}/broker/transactions/preview": { "post": { "tags": [ "Broker" ], "summary": "Preview a new share trade", "description": "Requires investments:write and update permission. Token administration allowlist and current tenant membership always apply. Read-only financial proposal. Shares and Bank cash may use distinct supported currencies, with separate actual trade/payment amounts and conversions. A sale whose fees/withholding exceed proceeds results in outgoing cash; zero net cash has no fictitious payment. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesPreview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesSourceInput" } } } } } }, "/administrations/{administration_public_id}/broker/transactions": { "post": { "tags": [ "Broker" ], "summary": "Confirm and store a share trade", "description": "Requires investments:write and update permission. Token administration allowlist and current tenant membership always apply. Stores source, all trade/cash journals, changed dependent sources and audit/retry receipt in one transaction. Retries return Idempotent-Replay=true; completed replies follow current corrected source facts. A replay for a removed source returns 410 with a safe tombstone. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesResult" } } }, "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether this response reuses a completed command." } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." }, "410": { "description": "Completed command target was subsequently removed. No historical input or calculation is returned in the retry tombstone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesResult" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesConfirmation" } } } } } }, "/administrations/{administration_public_id}/broker/transactions/{public_id}": { "get": { "tags": [ "Broker" ], "summary": "Read an active share source or its minimal deletion marker", "description": "Requires investments:read and view permission. Token administration allowlist and current tenant membership always apply. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesDetail" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } } }, "patch": { "tags": [ "Broker" ], "summary": "Confirm a joint share correction", "description": "Requires investments:write and update permission. Token administration allowlist and current tenant membership always apply. Retains source/payment/journal identities; a wrong action, instrument or depot can be corrected. Changed dependent transactions and changed/deleted cash entries are confirmed jointly. Unchanged payments may remain in closed years; actual changed journals require open periods. A financially equivalent correction does not add a source/journal revision. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesResult" } } }, "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether this response reuses a completed command." } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." }, "410": { "description": "Completed command target was subsequently removed. No historical input or calculation is returned in the retry tombstone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesResult" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesConfirmation" } } } } }, "delete": { "tags": [ "Broker" ], "summary": "Confirm removal of a share source", "description": "Requires investments:write and update permission. Token administration allowlist and current tenant membership always apply. Use a removal-preview token. Root and owned cash journals and source rows become minimal tombstones. Economic source fields, calculations, source-version JSON and settlement amounts/account/date/input are cleared atomically. Financial audit is retained; completed retry replies are redacted. Remaining transactions must form a financially valid chain. No Bank link is silently removed. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesResult" } } }, "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether this response reuses a completed command." } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." }, "410": { "description": "Completed command target was subsequently removed. No historical input or calculation is returned in the retry tombstone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesResult" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesConfirmation" } } } } } }, "/administrations/{administration_public_id}/broker/transactions/{public_id}/preview": { "post": { "tags": [ "Broker" ], "summary": "Preview a joint share correction", "description": "Requires investments:write and update permission. Token administration allowlist and current tenant membership always apply. Full replacement input through the same financial contract; no write. Original and destination instrument pools are read once each if the instrument changes. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesPreview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesSourceInput" } } } } } }, "/administrations/{administration_public_id}/broker/transactions/{public_id}/removal-preview": { "post": { "tags": [ "Broker" ], "summary": "Preview removal and dependent financial effects", "description": "Requires investments:write and update permission. Token administration allowlist and current tenant membership always apply. Empty body. Generates a source-bound removal proposal with affected cash and dependent GL entries, without mutations. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesPreview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "group_updates": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only updated group facts. Sealed, authorized and saved atomically with the ordinary source; never stored in the ordinary transaction input. If facts are invalidated, 422 returns error.details.group_updates with required statement identities and facts." } } } } } } } }, "/administrations/{administration_public_id}/broker": { "get": { "tags": [ "Broker" ], "summary": "Read current open share positions and transactions", "description": "Requires investments:read and view permission. Token administration allowlist and current tenant membership always apply. ", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesOverview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } } } }, "/administrations/{administration_public_id}/broker/cash-day-order": { "get": { "tags": [ "Broker" ], "summary": "Read actual cash movements available for same-day placement", "description": "Requires investments:read and view permission. Token administration allowlist and current tenant membership always apply. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "account", "in": "query", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 }, "description": "Bank account public identity in this administration." }, { "name": "exclude", "in": "query", "schema": { "type": "string", "minLength": 26, "maxLength": 26 }, "description": "Retained payment public identity to exclude." }, { "name": "source", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Ulid" }, "description": "Owning current share source while editing. Includes its same-day partial payments on other Bank accounts, so their actual order can be selected explicitly." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "public_id", "description" ], "properties": { "public_id": { "type": "string" }, "description": { "type": "string" } } } } } } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } } } }, "/administrations/{administration_public_id}/broker/reconciliation": { "get": { "tags": [ "Broker" ], "summary": "Read dated share and cash reconciliation", "description": "Requires investments:read and view permission. Token administration allowlist and current tenant membership always apply. Shares and Options use this same financial endpoint; Options have no dividend action. Physical option delivery and its share movement are confirmed and corrected atomically.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Defaults to today in administration timezone. Must fall inside a recorded fiscal year." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesReconciliation" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } } } }, "/administrations/{administration_public_id}/broker/interest-sources": { "get": { "tags": [ "Broker" ], "summary": "Available earlier bond interest sources", "operationId": "brokerInterestSources", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "instrument", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "long", "short" ] } }, { "name": "exclude", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "day_order", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Explicit earlier same-bond/side interest sources remaining before the proposed dated transaction. Requires investments:read and administration access.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "public_id", "date", "action", "amount", "currency" ], "properties": { "public_id": { "type": "string" }, "date": { "type": "string" }, "action": { "type": "string" }, "amount": { "type": "string", "description": "Exact remaining amount as a currency decimal, never a rational fraction or inferred base-currency amount." }, "currency": { "type": "string" }, "journal_number": { "type": [ "integer", "null" ], "description": "Displayed original journal number to distinguish equal-date interest sources. It is not used to infer financial order." } } } } } } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Invalid dated source request" } } } }, "/administrations/{administration_public_id}/broker/participation-facts": { "get": { "tags": [ "Broker" ], "summary": "Dated participation facts before the proposed source", "operationId": "brokerParticipationFacts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "instrument", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "day_order", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requires investments:read and active administration access. Dated source-derived carrying/exemption/reserves for form guidance; actual preview/confirmation rereads and checks all sources. Null when no earlier state exists. needs_order is true on an occupied date without an explicit actual-order anchor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshParticipationsFacts" } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Invalid dated source request" }, "404": { "description": "Unknown, wrong-administration or non-participation source." } } } }, "/administrations/{administration_public_id}/broker/settings": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "showBrokerSettings", "summary": "Read Broker ledger mappings", "description": "Uses investments:read. Roles use separate eligible accounts. Only existing foreign-currency bindings may be changed. Posted or opening-balance accounts stay mapped. Revision checks prevent stale writes; the complete update and its financial audit are atomic.", "responses": { "200": { "description": "Broker account mappings.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-required-abilities": [ "investments:read" ] }, "put": { "operationId": "updateBrokerSettings", "summary": "Change unused Broker ledger mappings", "description": "Uses investments:write. Roles use separate eligible accounts. Only existing foreign-currency bindings may be changed. Posted or opening-balance accounts stay mapped. Revision checks prevent stale writes; the complete update and its financial audit are atomic.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutBrokerSettingsRequest" } } } }, "responses": { "200": { "description": "Broker account mappings.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-required-abilities": [ "investments:write" ] } }, "/administrations/{administration_public_id}/broker/group-valuations/preview": { "post": { "tags": [ "Broker" ], "summary": "Preview joint valuation", "description": "Requires investments:write plus current update permission, active membership and token administration allowlist. Pure preview: confirm binds exact tenant, principal, command key, revisions, ordinary source and group evidence. Changes use the existing locked financial transaction; no partial writes. A closed affected year or inconsistent evidence fails closed. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupPreview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupInput" } } } } } }, "/administrations/{administration_public_id}/broker/group-valuations/{public_id}/preview": { "post": { "tags": [ "Broker" ], "summary": "Preview joint valuation", "description": "Requires investments:write plus current update permission, active membership and token administration allowlist. Pure preview: confirm binds exact tenant, principal, command key, revisions, ordinary source and group evidence. Changes use the existing locked financial transaction; no partial writes. A closed affected year or inconsistent evidence fails closed. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupPreview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupInput" } } } } } }, "/administrations/{administration_public_id}/broker/group-valuations/{public_id}/removal-preview": { "post": { "tags": [ "Broker" ], "summary": "Preview joint valuation", "description": "Requires investments:write plus current update permission, active membership and token administration allowlist. Pure preview: confirm binds exact tenant, principal, command key, revisions, ordinary source and group evidence. Changes use the existing locked financial transaction; no partial writes. A closed affected year or inconsistent evidence fails closed. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupPreview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "trade_date": { "type": "string", "format": "date" }, "group_updates": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only explicit continuation facts for later disposals that already exist when introducing or moving a historical group. The 422 response supplies the stable predecessor identity, including an unsaved main statement. No financial targets are copied automatically. The complete dated chain is sealed and saved atomically; never stored inside a source input." } } } } } } } }, "/administrations/{administration_public_id}/broker/group-valuations/confirm": { "post": { "tags": [ "Broker" ], "summary": "Confirm joint valuation", "description": "Requires investments:write plus current update permission, active membership and token administration allowlist. Pure preview: confirm binds exact tenant, principal, command key, revisions, ordinary source and group evidence. Changes use the existing locked financial transaction; no partial writes. A closed affected year or inconsistent evidence fails closed. A complete Broker request/confirmation recipe permits at most 250 settlements, targets and reserve_allocations combined, including those same row lists in follow-up input. Exceeding this budget returns validation_failed before financial processing. Existing independent bounds for other lists remain in force. API request throttling continues through api-write.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupResponse" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupResponse" } } } }, "410": { "description": "The original source has since been deleted; only its minimal current tombstone is returned on replay." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshSharesConfirmation" } } } } } }, "/administrations/{administration_public_id}/broker/group-valuations": { "get": { "tags": [ "Broker" ], "summary": "Read current joint valuations", "description": "Requires investments:read plus current view permission, active tenant membership and token administration allowlist.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupOverview" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } } } }, "/administrations/{administration_public_id}/broker/group-valuations/{public_id}": { "get": { "tags": [ "Broker" ], "summary": "Read current joint valuations", "description": "Requires investments:read plus current view permission, active tenant membership and token administration allowlist.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerGroupResponse" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration access." }, "404": { "description": "Source/instrument not found in this administration." }, "409": { "description": "Command key reused with different financial input or business-state conflict." }, "422": { "description": "Invalid input, stale proposal, closed affected period, inconsistent source/GL proof, unavailable account or currency not yet connected. Nothing partially stored." } } } }, "/administrations/{administration_public_id}/loans": { "get": { "tags": [ "Loans" ], "summary": "List loans", "description": "Requires loans:read, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoanSummary" } }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Loans" ], "summary": "Register a loan and optional schedule", "description": "Requires BOTH loans:write and ledger_accounts:write, current administration access, active membership and the corresponding role. API token allowlist applies. Registration atomically creates a dedicated principal account and links a compatible shared interest account, creating it if missing. Correct RGS 3.8 references and loan currency are applied; no journal entry or opening balance is posted. Borrowed principal defaults to other_long_term_liabilities (BLasOlsOsl), lent principal to other_receivables (BVorOvrOvk). Interest expense uses WFbeRlsRef; loan interest income uses WFbeRlmAre, not bank interest WFbeRlmObr. An unpaid-interest account remains optional. Initial revision is 1. Existing loans are not provisioned on reads or ordinary edits.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Loan" }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanRegisterInput" } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}": { "get": { "tags": [ "Loans" ], "summary": "Read a loan and its ledger balances", "description": "Requires loans:read, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Loan" }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Loans" ], "summary": "Edit the loan register and schedule", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Changing an unused loan currency also updates its linked dedicated principal and unpaid-interest accounts atomically and additionally requires ledger_accounts:write. Account identities, codes and RGS are retained; interest result stays in accounting currency. Ordinary name/contact/schedule edits do not change accounts. Used currencies/accounts retain their existing protections.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Loan" }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanRegisterUpdate" } } } } }, "delete": { "tags": [ "Loans" ], "summary": "Remove a loan without financial use", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "204": { "description": "Removed. Minimal identity tombstone and audit retained; no content." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}/accounts": { "put": { "tags": [ "Loans" ], "summary": "Set loan account mappings before use", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Loan" }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanAccountsInput" } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}/transactions": { "get": { "tags": [ "Loans" ], "summary": "List active loan bookings", "description": "Requires loans:read, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoanTransaction" } }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Loans" ], "summary": "Confirm a new loan booking", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoanTransaction" }, "links": { "type": "object" } }, "required": [ "data" ] } } }, "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether this command was replayed without writing." } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanTransactionConfirm" } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}/transactions/preview": { "post": { "tags": [ "Loans" ], "summary": "Preview a new loan booking", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoanPreview" }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanTransactionInput" } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}/transactions/{transaction_public_id}": { "put": { "tags": [ "Loans" ], "summary": "Correct a loan booking preserving its identities", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoanTransaction" }, "links": { "type": "object" } }, "required": [ "data" ] } } }, "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether this command was replayed without writing." } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanTransactionUpdateConfirm" } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}/transactions/{transaction_public_id}/preview": { "post": { "tags": [ "Loans" ], "summary": "Preview a booking correction", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoanPreview" }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanTransactionUpdate" } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}/transactions/{transaction_public_id}/delete-preview": { "post": { "tags": [ "Loans" ], "summary": "Preview booking deletion", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoanPreview" }, "links": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanDeletePreviewInput" } } } } } }, "/administrations/{administration_public_id}/loans/{loan_public_id}/transactions/{transaction_public_id}/delete": { "post": { "tags": [ "Loans" ], "summary": "Remove financial facts with a minimal tombstone", "description": "Requires loans:write, current administration access, active membership and the corresponding role. API token allowlist applies. Used currencies/accounts are fixed; bank links and closed years are protected. Financial previews do not write. Confirmations validate the current state and write atomically.", "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "loan_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoanTransaction" }, "links": { "type": "object" } }, "required": [ "data" ] } } }, "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether this command was replayed without writing." } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanDeleteConfirmInput" } } } } } }, "/administrations/{administration_public_id}/rekening-courant/interest": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listCurrentAccountInterest", "summary": "List the current administration’s interest entries", "description": "Requires rekening_courant:read.", "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/Cursor" } ] }, "post": { "operationId": "postCurrentAccountInterest", "summary": "Record current-account interest as an ordinary journal", "description": "Requires rekening_courant:write. Uses existing journal ownership, open-year, currency, revision and mutation controls. No automatic correction chain. Idempotent command with the ordinary journal identity. The original validated input is fingerprinted before recalculation; retry the exact command. state_hash from preview is required for saving.", "responses": { "201": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostedJournalEntryResponse" } } }, "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestPostRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/administrations/{administration_public_id}/rekening-courant/interest/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewCurrentAccountInterest", "summary": "Calculate and preview current-account interest", "description": "Requires rekening_courant:write. Preview only; no journal, receipt or metadata is stored. Returns state_hash for explicit confirmation.", "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/rekening-courant/interest/{journal_entry_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "journal_entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "showCurrentAccountInterest", "summary": "Read interest inputs and captured journal revision", "description": "Requires rekening_courant:read.", "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "editCurrentAccountInterest", "summary": "Edit the same ordinary interest journal", "description": "Requires rekening_courant:write. Uses existing journal ownership, open-year, currency, revision and mutation controls. No automatic correction chain. Idempotent command with the ordinary journal identity. The original validated input is fingerprinted before recalculation; retry the exact command. state_hash from preview is required for saving.", "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostedJournalEntryResponse" } } }, "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestEditRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/administrations/{administration_public_id}/rekening-courant/interest/{journal_entry_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "journal_entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewCurrentAccountInterestEdit", "summary": "Recalculate excluding the journal being edited", "description": "Requires rekening_courant:write and current expected_revision. Excludes this journal from both the calculator and RC allocation. No writes.", "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccountInterestEditPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/invoices/mollie-settings": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getMollieSettings", "description": "Requires sales:read and current owner/manager access. Never returns the API key. Response is private, no-store.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MollieSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateMollieSettings", "description": "Requires sales:write and current owner/manager access. Choose exactly one existing bank_account_public_id or new_bank_account. New account creation additionally requires banking:write and ledger_accounts:write and uses ordinary Bank creation atomically with these settings, without posting a financial entry. Values must be supplied explicitly; occupied ledger codes are rejected, never replaced. Old payment mandates retain their original account; verified credentials may rotate within the same profile/mode. Disabling an existing connection without a new key requires no Mollie request. The command key identifies the audit action; expected_revision prevents repeated changes. A stale revision is validation failure, not replay.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MollieSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MollieSettingsInput" } } } } } }, "/administrations/{administration_public_id}/invoices/mollie-payments": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listMolliePayments", "description": "Requires sales:read and current administration access. Minimal references only, never credentials or full Mollie responses.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MolliePaymentsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ] } }, "/administrations/{administration_public_id}/invoices/mollie-payments/{payment_public_id}/refresh": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "payment_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "refreshMolliePayment", "description": "Requires sales:write and owner/manager access. No body fields. Fetches verified Mollie facts; a paid payment produces at most one ordinary receipt under its original mandate. Exceptions remain visible for review. No automatic credit notes, exchange rates or changed posting dates.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MolliePaymentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "description": "Mollie response cannot be verified or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/administrations/{administration_public_id}/vat-return-payments": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "createVatReturnPayment", "summary": "Record a VAT payment or receipt", "description": "Requires vat_returns:write, current owner/manager authorization, active administration, API entitlement and token allowlist. Confirmation uses a fresh state_hash and Idempotency-Key; replay rechecks authorization. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/administrations/{administration_public_id}/vat-return-payments/obligations": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listVatReturnObligations", "summary": "List separate VAT return obligations and residuals", "description": "Requires vat_returns:read, current administration access, API entitlement and token allowlist. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnObligationsResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/vat-return-payments/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewVatReturnPayment", "summary": "Preview a VAT payment or receipt", "description": "Requires vat_returns:write, current owner/manager authorization, active administration, API entitlement and token allowlist. Confirmation uses a fresh state_hash and Idempotency-Key; replay rechecks authorization. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentPreviewResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/vat-return-payments/{payment_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "payment_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "showVatReturnPayment", "summary": "Show a VAT payment or removed identity", "description": "Requires vat_returns:read, current administration access, API entitlement and token allowlist. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "410": { "description": "Removed payment identity; financial audit is retained." } } }, "put": { "operationId": "updateVatReturnPayment", "summary": "Correct a VAT payment", "description": "Requires vat_returns:write, current owner/manager authorization, active administration, API entitlement and token allowlist. Confirmation uses a fresh state_hash and Idempotency-Key; replay rechecks authorization. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "delete": { "operationId": "deleteVatReturnPayment", "summary": "Remove an incorrectly entered VAT payment", "description": "Requires vat_returns:write, current owner/manager authorization, active administration, API entitlement and token allowlist. Confirmation uses a fresh state_hash and Idempotency-Key; replay rechecks authorization. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentRemovalRequest" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/administrations/{administration_public_id}/vat-return-payments/{payment_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "payment_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewVatReturnPaymentUpdate", "summary": "Preview a VAT payment correction", "description": "Requires vat_returns:write, current owner/manager authorization, active administration, API entitlement and token allowlist. Confirmation uses a fresh state_hash and Idempotency-Key; replay rechecks authorization. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentPreviewResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/vat-return-payments/{payment_public_id}/removal-preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "payment_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewVatReturnPaymentRemoval", "summary": "Preview removal of an incorrect VAT payment", "description": "Requires vat_returns:write, current owner/manager authorization, active administration, API entitlement and token allowlist. Confirmation uses a fresh state_hash and Idempotency-Key; replay rechecks authorization. EUR bank accounts in the same EUR administration only. Historical VAT balance account must be proven. Regular returns and supplementations have separate obligations; corrections/removal retain actual payments. Real payments may precede submission and exceed the obligation. Existing bank links must be removed explicitly before payment edits/removal. No financial choices or postings occur during reads or previews.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatReturnPaymentRemovalPreviewResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/broker/instruments": { "get": { "tags": [ "Broker" ], "summary": "List current instruments", "description": "Requires investments:read and current administration access. Uses the same investments permissions as other Broker functions. Financial rows and historical source inputs are unchanged.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerInstrumentPage" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration allowlist." }, "404": { "description": "Instrument or administration not accessible." }, "422": { "description": "Invalid metadata or stale revision. Nothing changed." } } } }, "/administrations/{administration_public_id}/broker/instruments/{public_id}": { "get": { "tags": [ "Broker" ], "summary": "Read an instrument with linked positions and transactions", "description": "Requires investments:read and current administration access. Uses the same investments permissions as other Broker functions. Financial rows and historical source inputs are unchanged.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerInstrumentDetail" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration allowlist." }, "404": { "description": "Instrument or administration not accessible." }, "422": { "description": "Invalid metadata or stale revision. Nothing changed." } } }, "put": { "tags": [ "Broker" ], "summary": "Correct current descriptive instrument data", "description": "Requires investments:write and current administration access. Uses the same investments permissions as other Broker functions. Financial rows and historical source inputs are unchanged.", "parameters": [ { "name": "administration_public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } }, { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 26, "maxLength": 26 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerInstrumentUpdateResult" } } } }, "401": { "description": "Not authenticated." }, "403": { "description": "Insufficient current permission, token ability or administration allowlist." }, "404": { "description": "Instrument or administration not accessible." }, "422": { "description": "Invalid metadata or stale revision. Nothing changed." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerInstrumentUpdate" } } } } } }, "/administrations/{administration_public_id}/purchases/settlements/{purchase_settlement_public_id}/delete-preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "purchase_settlement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewDeletePurchaseSettlement", "summary": "Preview removal of a purchase payment and existing currency valuation adjustments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_revision" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Read-only removal preview; use its state_hash to confirm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSettlementRemovalPreview" } } } }, "409": { "$ref": "#/components/responses/BusinessConflict" } } } }, "/administrations/{administration_public_id}/fiscal-years/{fiscal_year_public_id}/opening-balance/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/FiscalYearPublicId" } ], "post": { "operationId": "previewOpeningBalance", "summary": "Preview an opening balance and its existing currency-valuation effects", "description": "Requires opening_balances:write. Read-only: no opening, journal, audit entry or command key is created. Existing closing rates are reused. Missing rates are returned as a control point. Submit the returned state_hash with the same input to PUT; an empty lines array previews clearing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewOpeningBalanceRequest" } } } }, "responses": { "200": { "description": "Complete opening balance preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalancePreview" } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/rekening-courant/transactions/{transaction_public_id}/delete-preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "transaction_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewDeleteCurrentAccountTransaction", "summary": "Preview deletion with all existing currency valuation effects", "description": "Read-only. Requires rekening_courant:write for every actual owner. No Idempotency-Key is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewDeleteCurrentAccountTransactionRequest" } } } }, "responses": { "200": { "description": "Complete deletion proposal; nothing has been posted", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountRemovalPreview" } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/historical-origins": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getHistoricalCreditOrigins", "summary": "Get historical credit origins", "description": "Requires sales:read. Capacity-only historical attribution for an existing external credit in the administration currency under ordinary Dutch invoice VAT. No journal, VAT event, receipt, refund or bank link changes. Can be confirmed in a closed source year. Both source and credit capacity are checked under the existing administration lock. Existing source and journal identities remain unchanged. Uses the separate attribution revision, not the financial document revision.", "responses": { "200": { "description": "Get historical credit origins", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalCreditOriginsReadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateHistoricalCreditOrigins", "summary": "Confirm historical credit origins", "description": "Requires sales:write. Capacity-only historical attribution for an existing external credit in the administration currency under ordinary Dutch invoice VAT. No journal, VAT event, receipt, refund or bank link changes. Can be confirmed in a closed source year. Both source and credit capacity are checked under the existing administration lock. Existing source and journal identities remain unchanged. Uses the separate attribution revision, not the financial document revision.", "responses": { "200": { "description": "Confirm historical credit origins", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalCreditOriginsResultResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalCreditOriginsCommand" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/administrations/{administration_public_id}/sales/documents/{sales_document_public_id}/historical-origins/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "sales_document_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewHistoricalCreditOrigins", "summary": "Preview historical credit origins", "description": "Requires sales:write. Capacity-only historical attribution for an existing external credit in the administration currency under ordinary Dutch invoice VAT. No journal, VAT event, receipt, refund or bank link changes. Can be confirmed in a closed source year. Both source and credit capacity are checked under the existing administration lock. Existing source and journal identities remain unchanged. Uses the separate attribution revision, not the financial document revision.", "responses": { "200": { "description": "Preview historical credit origins", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalCreditOriginsPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalCreditOriginsInput" } } } } } }, "/administrations/{administration_public_id}/sales/opening-items": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "get": { "operationId": "indexSalesOpeningTradeItem", "summary": "index sales opening item", "description": "Uses existing sales:read authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" } ] }, "post": { "operationId": "createSalesOpeningTradeItem", "summary": "create sales opening item", "description": "Uses existing sales:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "201": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOpeningTradeItemInput" } } } } } }, "/administrations/{administration_public_id}/sales/opening-items/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "post": { "operationId": "previewSalesOpeningTradeItem", "summary": "preview sales opening item", "description": "Uses existing sales:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemInput" } } } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "showSalesOpeningTradeItem", "summary": "show sales opening item", "description": "Uses existing sales:read authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "put": { "operationId": "updateSalesOpeningTradeItem", "summary": "update sales opening item", "description": "Uses existing sales:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOpeningTradeItemInput" } } } } }, "delete": { "operationId": "deleteSalesOpeningTradeItem", "summary": "delete sales opening item", "description": "Uses existing sales:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOpeningTradeItemRemovalInput" } } } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "updatePreviewSalesOpeningTradeItem", "summary": "updatePreview sales opening item", "description": "Uses existing sales:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemInput" } } } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/removal-preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "removalPreviewSalesOpeningTradeItem", "summary": "removalPreview sales opening item", "description": "Uses existing sales:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemRemovalPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemRemovalInput" } } } } } }, "/administrations/{administration_public_id}/purchases/opening-items": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "get": { "operationId": "indexPurchasesOpeningTradeItem", "summary": "index purchases opening item", "description": "Uses existing purchases:read authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PerPage" } ] }, "post": { "operationId": "createPurchasesOpeningTradeItem", "summary": "create purchases opening item", "description": "Uses existing purchases:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "201": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOpeningTradeItemInput" } } } } } }, "/administrations/{administration_public_id}/purchases/opening-items/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "post": { "operationId": "previewPurchasesOpeningTradeItem", "summary": "preview purchases opening item", "description": "Uses existing purchases:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemInput" } } } } } }, "/administrations/{administration_public_id}/purchases/opening-items/{opening_item_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "showPurchasesOpeningTradeItem", "summary": "show purchases opening item", "description": "Uses existing purchases:read authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "put": { "operationId": "updatePurchasesOpeningTradeItem", "summary": "update purchases opening item", "description": "Uses existing purchases:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOpeningTradeItemInput" } } } } }, "delete": { "operationId": "deletePurchasesOpeningTradeItem", "summary": "delete purchases opening item", "description": "Uses existing purchases:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOpeningTradeItemRemovalInput" } } } } } }, "/administrations/{administration_public_id}/purchases/opening-items/{opening_item_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "updatePreviewPurchasesOpeningTradeItem", "summary": "updatePreview purchases opening item", "description": "Uses existing purchases:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemInput" } } } } } }, "/administrations/{administration_public_id}/purchases/opening-items/{opening_item_public_id}/removal-preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "removalPreviewPurchasesOpeningTradeItem", "summary": "removalPreview purchases opening item", "description": "Uses existing purchases:write authorization. Dedicated opening specifications do not create invoices or revenue/cost/VAT entries. Exact source and opening revisions bind consequential corrections.", "responses": { "200": { "description": "Checked opening item result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemRemovalPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningTradeItemRemovalInput" } } } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/receipts/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "openingPreviewSalesReceipt", "summary": "Preview an opening-item receipt", "description": "Uses the same source-owned financial command as the web. The path identifies a genuine customer opening item, never an invoice. Receipts require a receivable; refunds require a payable. Injected document_public_id/opening_item_public_id body fields are rejected. Current sales:write, role, tenant and token scope are checked; cross-administration payments additionally require rekening_courant:write for every affected administration. Exact cash, fiscal facts, stale previews and idempotent confirmations use the existing settlement contract.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementInput" } } } }, "responses": { "200": { "description": "Preview a sales receipt", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/receipts": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "openingPostSalesReceipt", "summary": "Record an opening-item receipt", "description": "Uses the same source-owned financial command as the web. The path identifies a genuine customer opening item, never an invoice. Receipts require a receivable; refunds require a payable. Injected document_public_id/opening_item_public_id body fields are rejected. Current sales:write, role, tenant and token scope are checked; cross-administration payments additionally require rekening_courant:write for every affected administration. Exact cash, fiscal facts, stale previews and idempotent confirmations use the existing settlement contract.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSalesSettlementRequest" } } } }, "responses": { "201": { "description": "Post a sales receipt", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/refunds/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "openingPreviewSalesRefund", "summary": "Preview an opening-item refund", "description": "Uses the same source-owned financial command as the web. The path identifies a genuine customer opening item, never an invoice. Receipts require a receivable; refunds require a payable. Injected document_public_id/opening_item_public_id body fields are rejected. Current sales:write, role, tenant and token scope are checked; cross-administration payments additionally require rekening_courant:write for every affected administration. Exact cash, fiscal facts, stale previews and idempotent confirmations use the existing settlement contract.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementInput" } } } }, "responses": { "200": { "description": "Preview a sales refund", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/refunds": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "openingPostSalesRefund", "summary": "Record an opening-item refund", "description": "Uses the same source-owned financial command as the web. The path identifies a genuine customer opening item, never an invoice. Receipts require a receivable; refunds require a payable. Injected document_public_id/opening_item_public_id body fields are rejected. Current sales:write, role, tenant and token scope are checked; cross-administration payments additionally require rekening_courant:write for every affected administration. Exact cash, fiscal facts, stale previews and idempotent confirmations use the existing settlement contract.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSalesSettlementRequest" } } } }, "responses": { "201": { "description": "Post a sales refund", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/bad-debt/preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewOpeningBadDebt", "summary": "Preview opening receivable write-off", "description": "Same jointly checked write-off and actual VAT relief as the web. Historical evidence is required only when the source does not already prove it; supply it first through the existing opening-item correction preview and confirmation. No historical invoice or payment is invented. Existing write-off journals keep their identity; remove=true retains minimal journal tombstones and replans actual receipts/credits. sales:write, current roles, tenant access, locks and closed-year checks apply.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBadDebtInput" } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "200": { "description": "Preview opening receivable write-off", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBadDebtPreviewResponse" } } } } } } }, "/administrations/{administration_public_id}/sales/opening-items/{opening_item_public_id}/bad-debt": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "opening_item_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "saveOpeningBadDebt", "summary": "Save opening receivable write-off", "description": "Same jointly checked write-off and actual VAT relief as the web. Historical evidence is required only when the source does not already prove it; supply it first through the existing opening-item correction preview and confirmation. No historical invoice or payment is invented. Existing write-off journals keep their identity; remove=true retains minimal journal tombstones and replans actual receipts/credits. sales:write, current roles, tenant access, locks and closed-year checks apply.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostOpeningBadDebtRequest" } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/SalesSettlementNotFound" }, "409": { "$ref": "#/components/responses/SalesSettlementConflict" }, "410": { "$ref": "#/components/responses/DeletedIdempotencyReplay" }, "422": { "$ref": "#/components/responses/SalesSettlementValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "200": { "description": "Save opening receivable write-off", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBadDebtResponse" } } } } } } }, "/administrations/{administration_public_id}/bank/owner-movements/{movement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankOwnerMovement", "summary": "Read a typed owner capital movement", "description": "Requires banking:read. Returns public source identity, current revision, actual input and bank/journal links. A deleted source returns identity, revision and deleted=true without financial input. Stored input is proved against its current physical journal receipt.", "responses": { "200": { "description": "Current source, or minimal tombstone.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateBankOwnerMovement", "summary": "Edit the same owner source and journal", "description": "Requires banking:write and current owner/manager role. Confirms one preview hash and expected revision under the administration lock. Preserves source and J identity, compatible bank links and existing valuation journal identities. Retained inactive accounts may be kept; new accounts must be eligible. Same semantic input is a no-op. No counterposting or new history system.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOwnerMovementUpdate" } } } }, "responses": { "200": { "description": "Public identity and current revision." }, "410": { "description": "The source has already been removed." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteBankOwnerMovement", "summary": "Remove financial lines and keep minimal source/J identity", "description": "Requires banking:write, removal preview/hash and expected revision. Bank claims must first be explicitly unlinked. Removes current source financial input and receipt, keeps source/J identity and deletion metadata, and writes the existing audit log. Existing valuation journals are updated atomically.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOwnerMovementRemove" } } } }, "responses": { "204": { "description": "Removed, or idempotent replay of the same removal." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/owner-movements/{movement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankOwnerMovement", "summary": "Preview an owner movement correction or removal", "description": "Requires banking:write and current owner/manager authority. Read-only snapshot; no idempotency reservation or financial writes. operation=update includes complete source input; operation=remove contains expected_revision only. Returns the outer state_hash, unchanged flag, original J removal where applicable and all proposed valuation consequences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOwnerMovementPreviewRequest" } } } }, "responses": { "200": { "description": "Complete confirmation preview." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/tax-movements/{movement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankTaxMovement", "summary": "Read a typed corporate income tax movement", "description": "Requires banking:read. Returns public source identity, current revision, actual input and bank/journal links. A deleted source returns identity, revision and deleted=true without financial input. Stored input is proved against its current physical journal receipt.", "responses": { "200": { "description": "Current source, or minimal tombstone.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateBankTaxMovement", "summary": "Edit the same tax source and journal", "description": "Requires banking:write and current owner/manager role. Confirms one preview hash and expected revision under the administration lock. Preserves source and J identity, compatible bank links and existing valuation journal identities. Retained inactive accounts may be kept; new accounts must be eligible. Same semantic input is a no-op. No counterposting or new history system.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTaxMovementUpdate" } } } }, "responses": { "200": { "description": "Public identity and current revision." }, "410": { "description": "The source has already been removed." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteBankTaxMovement", "summary": "Remove financial lines and keep minimal source/J identity", "description": "Requires banking:write, removal preview/hash and expected revision. Bank claims must first be explicitly unlinked. Removes current source financial input and receipt, keeps source/J identity and deletion metadata, and writes the existing audit log. Existing valuation journals are updated atomically.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTaxMovementRemove" } } } }, "responses": { "204": { "description": "Removed, or idempotent replay of the same removal." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/tax-movements/{movement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankTaxMovement", "summary": "Preview an tax movement correction or removal", "description": "Requires banking:write and current owner/manager authority. Read-only snapshot; no idempotency reservation or financial writes. operation=update includes complete source input; operation=remove contains expected_revision only. Returns the outer state_hash, unchanged flag, original J removal where applicable and all proposed valuation consequences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTaxMovementPreviewRequest" } } } }, "responses": { "200": { "description": "Complete confirmation preview." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/opening-private": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "createBankOpeningPrivate", "summary": "Transfer an opening bank position to private", "description": "Requires banking:write. Uses the existing authority, financial locks and audit. Preserves source/J identity on edits and a minimal tombstone on removal. The original opening is never changed by this transfer. It is not eligible for bank matching.", "responses": { "403": { "description": "Current Bank authority or IB administration required." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale source, opening context, financial state or idempotency key." }, "422": { "description": "Invalid input or closed financial year." }, "201": { "description": "Current public source data or confirmation preview." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOpeningPrivateConfirm" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] } }, "/administrations/{administration_public_id}/bank/opening-private/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewNewBankOpeningPrivate", "summary": "Preview a new opening-position private transfer", "description": "Requires banking:write. Uses the existing authority, financial locks and audit. Preserves source/J identity on edits and a minimal tombstone on removal. The original opening is never changed by this transfer. It is not eligible for bank matching.", "responses": { "200": { "description": "Current public source data or confirmation preview." }, "403": { "description": "Current Bank authority or IB administration required." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale source, opening context, financial state or idempotency key." }, "422": { "description": "Invalid input or closed financial year." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOpeningPrivatePreviewRequest" } } } } } }, "/administrations/{administration_public_id}/bank/opening-private/{movement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankOpeningPrivate", "summary": "Read an opening-position private transfer", "description": "Requires banking:read. Uses the existing authority, financial locks and audit. Preserves source/J identity on edits and a minimal tombstone on removal. The original opening is never changed by this transfer. It is not eligible for bank matching.", "responses": { "200": { "description": "Current public source data or confirmation preview." }, "403": { "description": "Current Bank authority or IB administration required." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale source, opening context, financial state or idempotency key." }, "422": { "description": "Invalid input or closed financial year." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateBankOpeningPrivate", "summary": "Edit the same opening-position source and journal", "description": "Requires banking:write. Uses the existing authority, financial locks and audit. Preserves source/J identity on edits and a minimal tombstone on removal. The original opening is never changed by this transfer. It is not eligible for bank matching.", "responses": { "200": { "description": "Current public source data or confirmation preview." }, "403": { "description": "Current Bank authority or IB administration required." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale source, opening context, financial state or idempotency key." }, "422": { "description": "Invalid input or closed financial year." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOpeningPrivateConfirm" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] }, "delete": { "operationId": "deleteBankOpeningPrivate", "summary": "Remove financial lines and retain minimal source/J identity", "description": "Requires banking:write. Uses the existing authority, financial locks and audit. Preserves source/J identity on edits and a minimal tombstone on removal. The original opening is never changed by this transfer. It is not eligible for bank matching.", "responses": { "403": { "description": "Current Bank authority or IB administration required." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale source, opening context, financial state or idempotency key." }, "422": { "description": "Invalid input or closed financial year." }, "204": { "description": "Removed or idempotent replay of the same removal." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOwnerMovementRemove" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] } }, "/administrations/{administration_public_id}/bank/opening-private/{movement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankOpeningPrivate", "summary": "Preview an opening-position transfer correction or removal", "description": "Requires banking:write. Uses the existing authority, financial locks and audit. Preserves source/J identity on edits and a minimal tombstone on removal. The original opening is never changed by this transfer. It is not eligible for bank matching.", "responses": { "200": { "description": "Current public source data or confirmation preview." }, "403": { "description": "Current Bank authority or IB administration required." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale source, opening context, financial state or idempotency key." }, "422": { "description": "Invalid input or closed financial year." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankOpeningPrivatePreviewRequest" } } } } } }, "/administrations/{administration_public_id}/bank/balance-movements/{movement_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getBankBalanceMovement", "summary": "Read a typed existing balance liability movement", "description": "Requires banking:read. Returns public source identity, current revision, actual input and bank/journal links. A deleted source returns identity, revision and deleted=true without financial input. Stored input is proved against its current physical journal receipt.", "responses": { "200": { "description": "Current source, or minimal tombstone.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateBankBalanceMovement", "summary": "Edit the same balance source and journal", "description": "Requires banking:write and current owner/manager role. Confirms one preview hash and expected revision under the administration lock. Preserves source and J identity, compatible bank links and existing valuation journal identities. Retained inactive accounts may be kept; new accounts must be eligible. Same semantic input is a no-op. No counterposting or new history system.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankBalanceMovementUpdate" } } } }, "responses": { "200": { "description": "Public identity and current revision." }, "410": { "description": "The source has already been removed." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteBankBalanceMovement", "summary": "Remove financial lines and keep minimal source/J identity", "description": "Requires banking:write, removal preview/hash and expected revision. Bank claims must first be explicitly unlinked. Removes current source financial input and receipt, keeps source/J identity and deletion metadata, and writes the existing audit log. Existing valuation journals are updated atomically.", "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankBalanceMovementRemove" } } } }, "responses": { "204": { "description": "Removed, or idempotent replay of the same removal." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/balance-movements/{movement_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "movement_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewBankBalanceMovement", "summary": "Preview a balance movement correction or removal", "description": "Requires banking:write and current owner/manager authority. Read-only snapshot; no idempotency reservation or financial writes. operation=update includes complete source input; operation=remove contains expected_revision only. Returns the outer state_hash, unchanged flag, original J removal where applicable and all proposed valuation consequences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankBalanceMovementPreviewRequest" } } } }, "responses": { "200": { "description": "Complete confirmation preview." }, "403": { "description": "Current Bank authority, API entitlement or allowlist missing." }, "404": { "description": "Source not found within this administration." }, "409": { "description": "Stale source, financial state or idempotency conflict." }, "422": { "description": "Invalid input, closed financial year or incompatible linked bank claims. Unlink explicitly first when required." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/administrations/{administration_public_id}/bank/dividend-declarations": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "listDividendDeclarations", "summary": "List dividend declarations and actual liability balances", "description": "Requires banking:read. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Current authorized data." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createDividendDeclaration", "summary": "Record a dividend declaration", "description": "Requires banking:write. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "201": { "description": "Confirmed source identity." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DividendDeclarationCreate" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] } }, "/administrations/{administration_public_id}/bank/dividend-declarations/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewNewDividendDeclaration", "summary": "Preview a standalone dividend declaration", "description": "Requires banking:write. Read-only preview; no idempotency reservation. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Current authorized data." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DividendDeclarationPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/bank/dividend-declarations/{dividend_public_id}": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "dividend_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "get": { "operationId": "getDividendDeclaration", "summary": "Read a dividend declaration and real payment balances", "description": "Requires banking:read. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Current authorized data." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateDividendDeclaration", "summary": "Edit the same dividend declaration and J number", "description": "Requires banking:write. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Confirmed source identity." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DividendDeclarationUpdate" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] }, "delete": { "operationId": "deleteDividendDeclaration", "summary": "Remove only the declaration, preserving real payments", "description": "Requires banking:write. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Confirmed source identity." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DividendDeclarationRemove" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] } }, "/administrations/{administration_public_id}/bank/dividend-declarations/{dividend_public_id}/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" }, { "name": "dividend_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "post": { "operationId": "previewDividendDeclarationChange", "summary": "Preview declaration correction or removal", "description": "Requires banking:write. Read-only preview; no idempotency reservation. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Current authorized data." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DividendDeclarationPreviewRequest" } } } } } }, "/administrations/{administration_public_id}/bank/dividend-settings": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "get": { "operationId": "getDividendSettings", "summary": "Read explicitly configured dividend accounts", "description": "Requires banking:read. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Current authorized data." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateDividendSettings", "summary": "Configure existing accounts for future dividend declarations", "description": "Requires banking:write. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Confirmed source identity." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DividendSettingsInput" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] } }, "/administrations/{administration_public_id}/bank/dividend-payments/preview": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "previewDividendPayment", "summary": "Preview an actual dividend or withholding payment", "description": "Requires banking:write. Read-only preview; no idempotency reservation. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "200": { "description": "Current authorized data." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankDividendPaymentInput" } } } } } }, "/administrations/{administration_public_id}/bank/dividend-payments": { "parameters": [ { "$ref": "#/components/parameters/AdministrationPublicId" } ], "post": { "operationId": "createDividendPayment", "summary": "Record a payment without an imported bank row", "description": "Requires banking:write. Tenant-scoped, current role and API allowlist. Dividend settings apply to new declarations; stored source accounts and real payments remain independent. Corrections retain the original journal identity, with no counterpostings. No automatic tax exemption or mirror posting.", "responses": { "201": { "description": "Confirmed source identity." }, "403": { "description": "Current Bank authority missing." }, "404": { "description": "Source not found in this administration." }, "409": { "description": "Stale preview, conflicting command, or closed fiscal year." }, "422": { "description": "Invalid financial input." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankDividendPaymentConfirm" } } } }, "parameters": [ { "$ref": "#/components/parameters/BankTransferIdempotencyKey" } ] } }, "/administrations/{administration_public_id}/journal-entries/{journal_entry_public_id}/removal-preview": { "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/AdministrationPublicId" }, { "$ref": "#/components/parameters/JournalEntryPublicId" } ], "post": { "operationId": "previewJournalEntryRemoval", "summary": "Preview removal of a manual journal and its linked opening-item and periodic cash effects", "description": "Existing read-only route. Requires journal_entries:write and, for linked opening-item corrections, purchases:write. Accepts no input fields. Supply the returned expected_revision and state_hash to the existing delete command. No journal, link or audit row is changed.", "responses": { "200": { "description": "Current revision and complete removal effects", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalRemovalPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrAbilityNotAllowed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BusinessConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "personal access token", "description": "Send the complete token once obtained. Cookie/session authentication is not accepted." } }, "parameters": { "BankTransferIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Caller-generated key for one transfer mutation. Reuse the same key and exact input after an uncertain response. Completed identity is scoped to the principal, source administration and command kind; changed input returns bank_command_key_conflict (409). Does not promise an Idempotency-Replayed response header.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } }, "AcceptLanguage": { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "nl", "en" ], "default": "nl" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Caller-generated command key. The raw value is never persisted; reuse with another canonical payload returns idempotency_key_reused. The guarantee is no duplicate execution, not permanent storage of deleted financial content. After journal-entry or current-account Delete, completed results are irreversibly redacted to a tombstone-safe state; a prior Post/Edit replay returns 410. After opening-balance clear, prior results become data: null. Replays include Idempotency-Replayed: true.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } }, "AdministrationPublicId": { "name": "administration_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "FiscalYearPublicId": { "name": "fiscal_year_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "LedgerAccountPublicId": { "name": "ledger_account_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "ContactPublicId": { "name": "contact_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "ContactRelationshipPublicId": { "name": "contact_relationship_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "JournalEntryPublicId": { "name": "journal_entry_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "RevaluationPublicId": { "name": "revaluation_public_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "LedgerDateFrom": { "name": "date_from", "in": "query", "required": false, "description": "Inclusive period start within the selected fiscal year. Defaults to the fiscal-year start.", "schema": { "type": "string", "format": "date" } }, "LedgerDateTo": { "name": "date_to", "in": "query", "required": false, "description": "Inclusive period end within the selected fiscal year. Defaults to today for the current fiscal year and to the fiscal-year end otherwise.", "schema": { "type": "string", "format": "date" } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque signed keyset continuation returned by links.next and bound to the administration, fiscal year, account and period filters.", "schema": { "type": "string" } }, "PerPage": { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "ReportDateFrom": { "name": "date_from", "in": "query", "required": false, "description": "Inclusive report-period start within the selected fiscal year. Defaults to the fiscal-year start.", "schema": { "type": "string", "format": "date" } }, "ReportDateTo": { "name": "date_to", "in": "query", "required": false, "description": "Inclusive report-period end within the selected fiscal year. Defaults to today for a current fiscal year and to the fiscal-year end otherwise.", "schema": { "type": "string", "format": "date" } }, "ReportAsOf": { "name": "as_of", "in": "query", "required": false, "description": "Inclusive balance-sheet date within the selected fiscal year. Defaults to today for a current fiscal year, to ends_on for a historical fiscal year, and to starts_on for a future fiscal year.", "schema": { "type": "string", "format": "date" } }, "ReportIncludeZero": { "name": "include_zero", "in": "query", "required": false, "description": "Include zero-value accounts, classifications, groups and derived rows where applicable.", "schema": { "type": "boolean", "default": false } } }, "headers": { "ContentLanguage": { "description": "Language used for human-readable messages.", "schema": { "type": "string", "enum": [ "nl", "en" ] } }, "RequestId": { "description": "Public ULID identifying this request.", "schema": { "$ref": "#/components/schemas/Ulid" } }, "IdempotencyReplayed": { "description": "Present with value true only when a completed command result was replayed. If its target was deleted, the retained result is the redacted tombstone-safe state and never the former financial contents.", "schema": { "type": "string", "const": "true" } }, "RateLimitLimit": { "description": "Maximum requests in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Remaining requests in the current window.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds until a request may be retried.", "schema": { "type": "integer" } } }, "schemas": { "BankProviderPayoutPreview": { "type": "object", "additionalProperties": false, "required": [ "state_hash", "preview", "journals", "dependent_changes" ], "properties": { "state_hash": { "type": "string" }, "preview": { "type": "object" }, "journals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "administration_public_id", "administration_name", "currency_code", "date", "lines" ], "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_name": { "type": "string" }, "currency_code": { "type": "string" }, "date": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePreviewJournalLine" } } } } }, "dependent_changes": { "type": "array", "items": { "type": "object" } } } }, "ProviderPayoutIdentity": { "type": "object", "additionalProperties": false, "required": [ "public_id", "source_type" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "source_type": { "enum": [ "bank_transfer", "rekening_courant" ] } } }, "PostProviderPayoutRequest": { "type": "object", "additionalProperties": false, "required": [ "data", "state_hash" ], "properties": { "data": { "$ref": "#/components/schemas/BankProviderPayoutInput" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "PreviewProviderPayoutRequest": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankProviderPayoutInput" } } }, "BankProviderPayoutInput": { "type": "object", "additionalProperties": false, "required": [ "provider_bank_account_public_id" ], "properties": { "provider_bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "reference": { "type": [ "string", "null" ], "maxLength": 255 }, "transfer": { "$ref": "#/components/schemas/BankTransferInput" }, "rc": { "$ref": "#/components/schemas/ProviderPrivatePayoutInput" }, "fee": { "type": "object", "additionalProperties": false, "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "purchase_payment", "purchase_document" ] }, "data": { "oneOf": [ { "$ref": "#/components/schemas/BankPurchasePaymentInput" }, { "$ref": "#/components/schemas/BankPurchaseDocumentInput" } ] } } } }, "oneOf": [ { "required": [ "transfer" ], "not": { "required": [ "rc" ] } }, { "required": [ "rc" ], "not": { "required": [ "transfer" ] } } ] }, "ProviderPrivatePayoutInput": { "type": "object", "additionalProperties": false, "required": [ "target_type", "target_public_id", "settlement_ledger_account_public_id", "posting_date", "description", "direction", "native_amount" ], "properties": { "target_type": { "const": "contact" }, "target_public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "maxLength": 255 }, "direction": { "const": "outflow" }, "native_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankTransferEdgeAmount" } } } }, "UpdateSupplierCreditWriteoffRequest": { "type": "object", "additionalProperties": false, "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "state_hash", "expected_revision" ], "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "application_date": { "type": "string", "format": "date" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "PreviewUpdateSupplierCreditWriteoffRequest": { "type": "object", "additionalProperties": false, "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "expected_revision" ], "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "application_date": { "type": "string", "format": "date" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "PostSupplierCreditWriteoffRequest": { "type": "object", "additionalProperties": false, "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "state_hash" ], "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "application_date": { "type": "string", "format": "date" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" } } }, "PreviewSupplierCreditWriteoffRequest": { "type": "object", "additionalProperties": false, "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount" ], "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "application_date": { "type": "string", "format": "date" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" } } }, "PurchaseSupplierCreditWriteoffFields": { "type": "object", "additionalProperties": false, "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "application_date": { "type": "string", "format": "date" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" } }, "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount" ] }, "PurchaseAnnualCostAllocation": { "type": "object", "additionalProperties": false, "required": [ "line_number", "basis", "starts_on", "ends_on", "days", "slices", "unallocated_amount" ], "properties": { "line_number": { "type": "integer" }, "basis": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$" }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "slices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fiscal_year_public_id", "starts_on", "ends_on", "days", "amount", "posting_date" ], "properties": { "fiscal_year_public_id": { "type": "string" }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$" }, "posting_date": { "type": [ "string", "null" ] } } } }, "unallocated_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$" } } }, "PurchaseCostPeriod": { "type": "object", "additionalProperties": false, "required": [ "starts_on", "ends_on" ], "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" } } }, "CurrencyExchangeFeeInput": { "type": "object", "required": [ "amount", "currency_code", "handling" ], "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,15}(?:\\.[0-9]{1,12})?$", "description": "Strictly positive decimal string, at most 15 integer and 12 fractional digits, including EUR. Dot decimal separator; no exponent or localized formatting." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "handling": { "type": "string", "enum": [ "added_to_sold", "withheld_from_bought", "separate" ] }, "expense_ledger_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "Optional explicit source account. When omitted, a correction retains its proved source choice; otherwise the configured Broker transaction fee account is used and bound to the preview." }, "bank_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "date": { "type": "string", "format": "date" }, "base_value": { "type": "string", "pattern": "^[0-9]{1,15}(?:\\.[0-9]{1,12})?$", "description": "Strictly positive decimal string, at most 15 integer and 12 fractional digits, including EUR. Dot decimal separator; no exponent or localized formatting." } }, "additionalProperties": false, "description": "Fees are expensed directly on the explicitly selected eligible account. added_to_sold uses the sold currency and payment; withheld_from_bought uses the bought currency and receipt and cannot exceed the gross bought amount. separate requires its own actual Bank account and date. base_value is required only for a fee currency other than EUR and both principal currencies, and forbidden otherwise. Other fees use the same proven trade valuation as their principal currency. Cash dates must be on or after trade_date.", "allOf": [ { "if": { "properties": { "handling": { "const": "separate" } } }, "then": { "required": [ "bank_account_public_id", "date" ] }, "else": { "not": { "anyOf": [ { "required": [ "bank_account_public_id" ] }, { "required": [ "date" ] } ] } } } ] }, "CurrencyExchangeDayOrder": { "type": "object", "required": [ "phase" ], "properties": { "phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "anchor_phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "position": { "$ref": "#/components/schemas/CurrencyExchangePosition" } }, "additionalProperties": false, "description": "One exact gap per phase and account-day, or a legacy partial before/after relation. Legacy semantics are unchanged. Duplicate lanes and mixing a gap with a legacy journal placement for the same phase are rejected. Separate new-phase relations use phase_order.", "oneOf": [ { "required": [ "position" ], "not": { "anyOf": [ { "required": [ "placement" ] }, { "required": [ "journal_public_id" ] }, { "required": [ "anchor_phase" ] } ] } }, { "required": [ "placement", "journal_public_id" ], "not": { "anyOf": [ { "required": [ "position" ] }, { "required": [ "anchor_phase" ] } ] } }, { "required": [ "placement", "anchor_phase" ], "not": { "anyOf": [ { "required": [ "position" ] }, { "required": [ "journal_public_id" ] } ] } } ] }, "CurrencyExchangeInput": { "type": "object", "required": [ "trade_date", "sold_bank_account_public_id", "sold_amount", "bought_bank_account_public_id", "bought_amount" ], "properties": { "trade_date": { "type": "string", "format": "date" }, "sold_bank_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "sold_amount": { "type": "string", "pattern": "^[0-9]{1,15}(?:\\.[0-9]{1,12})?$", "description": "Strictly positive decimal string, at most 15 integer and 12 fractional digits, including EUR. Dot decimal separator; no exponent or localized formatting." }, "sold_date": { "type": "string", "format": "date" }, "bought_bank_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "bought_amount": { "type": "string", "pattern": "^[0-9]{1,15}(?:\\.[0-9]{1,12})?$", "description": "Strictly positive decimal string, at most 15 integer and 12 fractional digits, including EUR. Dot decimal separator; no exponent or localized formatting." }, "bought_date": { "type": "string", "format": "date" }, "principal_base_value": { "type": "string", "pattern": "^[0-9]{1,15}(?:\\.[0-9]{1,12})?$", "description": "Strictly positive decimal string, at most 15 integer and 12 fractional digits, including EUR. Dot decimal separator; no exponent or localized formatting." }, "fees": { "$ref": "#/components/schemas/CurrencyExchangeFeeInput" }, "rounding_ledger_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reference": { "type": [ "string", "null" ], "maxLength": 255 }, "day_order": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeDayOrder" }, "maxItems": 32 }, "rounding_gain_ledger_account_public_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "Optional explicit gain rounding account. Both directional accounts are supplied together. If omitted, the configured Broker payment-difference accounts are used and bound to the preview. Mutually exclusive with the historical single rounding account." }, "rounding_loss_ledger_account_public_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "Optional explicit loss rounding account. Both directional accounts are supplied together. If omitted, the configured Broker payment-difference accounts are used and bound to the preview. Mutually exclusive with the historical single rounding account." }, "settlement_mode": { "type": "string", "enum": [ "joint", "separate" ], "description": "Explicit source layout. joint uses one settlement date and one journal for both bank movements. separate preserves independently dated and ordered bank movements, including equal calendar dates. Legacy input without this field retains its historical three-phase contract." }, "settlement_date": { "type": "string", "format": "date", "description": "Actual shared settlement date, on or after trade_date. Required only for joint settlement; sold_date and bought_date are then forbidden." }, "phase_order": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/CurrencyExchangePhaseOrder" } }, "restoration_order": { "type": "array", "readOnly": true, "description": "Server-owned account-day placement evidence for the bounded manual-journal restoration. Returned for source inspection; omit this field from ordinary create/update requests. Current explicit placement is retained or changed through the existing day_order controls.", "items": { "type": "object", "additionalProperties": false, "required": [ "phase", "placement", "journal_public_id", "scope" ], "properties": { "phase": { "type": "string", "enum": [ "trade", "settlement" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "type": "string", "format": "ulid" }, "scope": { "type": "object", "additionalProperties": false, "required": [ "ledger_account_public_id", "date" ], "properties": { "ledger_account_public_id": { "type": "string", "format": "ulid" }, "date": { "type": "string", "format": "date" } } } } } } }, "additionalProperties": false, "description": "A real currency exchange with exact gross cash amounts. New explicit layout: joint with trade_date and settlement_date, or separate with trade_date, sold_date and bought_date. Legacy requests without settlement_mode retain the historical layout. Omitted posting accounts use configured Broker mappings; proven source choices remain authoritative on correction. Notes are not supported.", "dependentRequired": { "rounding_gain_ledger_account_public_id": [ "rounding_loss_ledger_account_public_id" ], "rounding_loss_ledger_account_public_id": [ "rounding_gain_ledger_account_public_id" ] }, "not": { "anyOf": [ { "required": [ "rounding_ledger_account_public_id", "rounding_gain_ledger_account_public_id" ] }, { "required": [ "rounding_ledger_account_public_id", "rounding_loss_ledger_account_public_id" ] } ] }, "oneOf": [ { "required": [ "settlement_mode", "settlement_date" ], "properties": { "settlement_mode": { "const": "joint" } }, "not": { "anyOf": [ { "required": [ "sold_date" ] }, { "required": [ "bought_date" ] } ] } }, { "required": [ "settlement_mode", "sold_date", "bought_date" ], "properties": { "settlement_mode": { "const": "separate" } }, "not": { "required": [ "settlement_date" ] } }, { "required": [ "sold_date", "bought_date" ], "not": { "anyOf": [ { "required": [ "settlement_mode" ] }, { "required": [ "settlement_date" ] } ] } } ] }, "CurrencyExchangeConfirmInput": { "type": "object", "required": [ "confirmation_token" ], "properties": { "confirmation_token": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "description": "Submit only the opaque token from preview with the same Idempotency-Key and authenticated principal. Financial input is taken from the bound proposal." }, "CurrencyExchangeFacts": { "type": "object", "required": [ "contract_version", "trade_date", "base_currency", "sold", "bought", "principal_base", "principal_booked", "fee", "cash_legs" ], "properties": { "contract_version": { "type": "integer", "const": 1 }, "trade_date": { "type": "string", "format": "date" }, "base_currency": { "type": "string", "const": "EUR" }, "sold": { "type": "object", "required": [ "currency", "native" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "native": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." } }, "additionalProperties": false }, "bought": { "type": "object", "required": [ "currency", "native" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "native": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." } }, "additionalProperties": false }, "principal_base": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." }, "principal_booked": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "fee": { "oneOf": [ { "type": "object", "required": [ "currency", "native", "handling", "exact_base", "booked_base" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "native": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." }, "handling": { "type": "string", "enum": [ "added_to_sold", "withheld_from_bought", "separate" ] }, "exact_base": { "type": "object", "required": [ "numerator", "denominator" ], "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "additionalProperties": false }, "booked_base": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "cash_legs": { "type": "array", "items": { "type": "object", "required": [ "role", "direction", "currency", "native" ], "properties": { "role": { "type": "string", "enum": [ "sold", "bought", "fees" ] }, "direction": { "type": "string", "enum": [ "DBIT", "CRDT" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "native": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." } }, "additionalProperties": false }, "minItems": 1, "maxItems": 3 } }, "additionalProperties": false, "description": "Exact source facts and original HalfUp EUR cent projections. cash_legs are the actual net movements, with a fee applied exactly once. A fully withheld receipt has no fictitious zero bank movement. These original values are not a substitute for the current carrying values in settlement journals." }, "CurrencyExchangeJournal": { "type": "object", "required": [ "source_type", "role", "public_id", "entry_number", "date", "description", "lines", "rounding" ], "properties": { "before": { "$ref": "#/components/schemas/CurrencyExchangeJournal", "description": "Existing valuation journal before an in-place update; keeps the same journal identity." }, "before_label": { "type": "string" }, "after_label": { "type": "string" }, "source_type": { "type": "string", "description": "Proven journal source type; generic trade/settlement roles do not imply an FX exchange." }, "administration_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "administration_name": { "type": "string" }, "role": { "type": "string", "description": "Exchange phase or retained dependent source phase." }, "public_id": { "oneOf": [ { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "entry_number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "account", "account_public_id", "side", "amount", "base_currency", "currency", "native", "native_currency" ], "properties": { "account": { "type": "string" }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Stored EUR ledger amount. It can be zero while the proven native amount is nonzero." }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "native": { "oneOf": [ { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." }, { "type": "null" } ] }, "native_currency": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, { "type": "null" } ] } }, "additionalProperties": false } }, "rounding": { "oneOf": [ { "type": "object", "required": [ "amount", "side", "account_public_id" ], "properties": { "amount": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "roundings": { "type": "array", "items": { "type": "object", "required": [ "amount", "side", "account_public_id" ], "properties": { "amount": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "cash_leg": { "type": "string", "enum": [ "sold", "bought", "fees" ], "description": "Present when the preview associates this rounding with an actual bank leg." } }, "additionalProperties": false }, "description": "All separately proven rounding amounts in this journal; a joint settlement may contain more than one. The scalar rounding field remains a compatibility projection of the first item." } }, "additionalProperties": false, "description": "Public journal projection without private database IDs or proof authority. Native values retain their exact precision; ledger values are EUR cents in storage format. Proven rounding is shown separately on the explicitly selected account, never silently labelled an FX result." }, "CurrencyExchangeSource": { "type": "object", "required": [ "public_id", "revision", "removed", "input", "facts", "journals", "bank_links" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "revision": { "type": "integer", "minimum": 1 }, "removed": { "type": "boolean" }, "input": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyExchangeInput" }, { "type": "null" } ] }, "facts": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyExchangeFacts" }, { "type": "null" } ] }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "bank_links": { "type": "array", "items": { "type": "object", "required": [ "bank_entry_public_id", "direction", "amount" ], "properties": { "bank_entry_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "direction": { "type": "string", "enum": [ "DBIT", "CRDT" ] }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." } }, "additionalProperties": false } }, "journal_entry_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "additionalProperties": false, "description": "Current source representation. A removed source is a tombstone: removed=true, input/facts=null and journals/bank_links empty. Confirmation responses additionally contain journal_entry_public_id. Completed command replay resolves the current source, not an old financial snapshot." }, "CurrencyExchangeResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CurrencyExchangeSource" } }, "additionalProperties": false }, "CurrencyExchangePreviewResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "confirmation_token", "source_public_id", "operation", "input", "facts", "journals", "removed_journals", "dependent_changes", "state_hash" ], "properties": { "confirmation_token": { "type": "string" }, "source_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "operation": { "type": "string", "enum": [ "create", "update", "remove" ] }, "input": { "$ref": "#/components/schemas/CurrencyExchangeInput" }, "facts": { "$ref": "#/components/schemas/CurrencyExchangeFacts" }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "removed_journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "dependent_changes": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeDependentJournal" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "day_order": { "type": "array", "items": { "type": "object", "required": [ "phase", "account", "date", "position" ], "additionalProperties": false, "properties": { "phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "account": { "type": "string" }, "date": { "type": "string", "format": "date" }, "position": { "type": "string" } } } } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Read-only complete proposal. Inspect root and dependent journals and any rounding before confirmation. Token binds administration, principal, command key, source revision/input, complete dependency state, order and accounts. Confirmation locks and rechecks current rights and state, then atomically stores the complete change; stale proposals must be refreshed." }, "CurrencyExchangeListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "public_id", "revision", "trade_date", "reference", "facts" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "revision": { "type": "integer", "minimum": 1 }, "trade_date": { "type": "string", "format": "date" }, "reference": { "type": [ "string", "null" ] }, "facts": { "$ref": "#/components/schemas/CurrencyExchangeFacts" } }, "additionalProperties": false } }, "meta": { "type": "object", "required": [ "current_page", "last_page", "total" ], "properties": { "current_page": { "type": "integer", "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Active sources only, ordered by trade_date descending and source ID descending, 25 per page." }, "CurrencyExchangeOrderRequired": { "type": "object", "required": [ "errors", "day_order_options" ], "properties": { "errors": { "type": "object", "required": [ "day_order" ], "properties": { "day_order": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "day_order_options": { "type": "object", "properties": { "trade": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "journal_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "anchor_phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "label": { "type": "string" } }, "additionalProperties": false, "oneOf": [ { "required": [ "journal_public_id" ], "not": { "required": [ "anchor_phase" ] } }, { "required": [ "anchor_phase" ], "not": { "required": [ "journal_public_id" ] } } ] } }, "sold": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "journal_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "anchor_phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "label": { "type": "string" } }, "additionalProperties": false, "oneOf": [ { "required": [ "journal_public_id" ], "not": { "required": [ "anchor_phase" ] } }, { "required": [ "anchor_phase" ], "not": { "required": [ "journal_public_id" ] } } ] } }, "bought": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "journal_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "anchor_phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "label": { "type": "string" } }, "additionalProperties": false, "oneOf": [ { "required": [ "journal_public_id" ], "not": { "required": [ "anchor_phase" ] } }, { "required": [ "anchor_phase" ], "not": { "required": [ "journal_public_id" ] } } ] } }, "fees": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "journal_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "anchor_phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "label": { "type": "string" } }, "additionalProperties": false, "oneOf": [ { "required": [ "journal_public_id" ], "not": { "required": [ "anchor_phase" ] } }, { "required": [ "anchor_phase" ], "not": { "required": [ "journal_public_id" ] } } ] } }, "positions": { "type": "array", "items": { "type": "object", "required": [ "key", "phase", "account", "date", "options" ], "additionalProperties": false, "properties": { "key": { "type": "string" }, "phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "account": { "type": "string" }, "date": { "type": "string", "format": "date" }, "options": { "type": "array", "items": { "type": "object", "required": [ "position", "label" ], "additionalProperties": false, "properties": { "position": { "$ref": "#/components/schemas/CurrencyExchangePosition" }, "label": { "type": "string" } } } } } } }, "phase_relations": { "type": "array", "items": { "type": "object", "required": [ "key", "phase", "anchor_phase" ], "additionalProperties": false, "properties": { "key": { "type": "string" }, "phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "anchor_phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] } } } } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Special HTTP 422 preview response when same-day evidence leaves a real tie. Top-level response, without a data envelope. Options are authorized proven anchors, grouped by phase. Resubmit the complete input with explicit day_order choices and obtain a fresh preview." }, "JournalEntryNoDifferenceState": { "type": "object", "required": [ "posting_date", "fiscal_year", "description", "status", "currency_code", "total_amount", "deleted_at" ], "properties": { "posting_date": { "type": "string", "format": "date" }, "fiscal_year": { "$ref": "#/components/schemas/JournalEntryFiscalYear" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "const": "no_difference" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "total_amount": { "type": "string", "pattern": "^0(?:\\.0+)?$" }, "deleted_at": { "type": "null" }, "source_type": { "const": "fx_revaluation" } } }, "NoDifferenceJournalEntrySummary": { "allOf": [ { "$ref": "#/components/schemas/JournalEntrySummaryBase" }, { "$ref": "#/components/schemas/JournalEntryNoDifferenceState" } ], "unevaluatedProperties": false }, "NoDifferenceJournalEntry": { "allOf": [ { "$ref": "#/components/schemas/JournalEntrySummaryBase" }, { "$ref": "#/components/schemas/JournalEntryNoDifferenceState" }, { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "maxItems": 0 } } } ], "unevaluatedProperties": false }, "FixedAssetPurchaseCandidate": { "type": "object", "additionalProperties": false, "required": [ "line_public_id", "document_public_id", "document_number", "external_number", "document_date", "supplier_name", "description", "account_code", "account_name", "currency_code", "available_amount", "error_code" ], "properties": { "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_number": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "document_date": { "type": "string", "format": "date" }, "supplier_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "account_code": { "type": "string" }, "account_name": { "type": "string" }, "currency_code": { "type": "string" }, "available_amount": { "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "error_code": { "type": [ "string", "null" ] } } }, "FixedAssetPurchaseCandidateListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetPurchaseCandidate" } }, "links": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } }, "meta": { "type": "object", "additionalProperties": false, "required": [ "per_page" ], "properties": { "per_page": { "type": "integer", "minimum": 1 } } } } }, "FixedAssetPurchasePreparationResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "values", "source" ], "properties": { "values": { "type": "object", "additionalProperties": false, "required": [ "source_type", "name", "acquired_on", "allocations", "in_use_on", "starts_on" ], "properties": { "source_type": { "const": "purchase" }, "name": { "type": [ "string", "null" ] }, "acquired_on": { "type": "string", "format": "date" }, "allocations": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/FixedAssetAllocationInput" } }, "acquisition_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "accumulated_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "in_use_on": { "type": "string", "format": "date" }, "starts_on": { "type": "string", "format": "date" }, "kind": { "enum": [ "goodwill", "machinery" ] } }, "description": "Editable purchase facts and suggestions: first use and register start use the document date, never today or an open fiscal year. Kind only for unambiguous goodwill/machinery classification. No residual or life estimate is inferred." }, "source": { "type": "object", "additionalProperties": false, "required": [ "administration_public_id", "document_public_id", "line_public_id", "source_revision", "source_state_hash", "document_type", "document_date", "performance_date", "ledger_account_public_id", "base_currency_code", "base_cost_amount", "allocated_amount", "available_amount" ], "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_revision": { "type": "integer", "minimum": 1 }, "source_state_hash": { "type": "string" }, "document_type": { "const": "purchase" }, "document_date": { "type": "string", "format": "date" }, "performance_date": { "type": "string", "format": "date" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "base_currency_code": { "type": "string" }, "base_cost_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "allocated_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "available_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } } } } }, "FixedAssetPosting": { "type": "object", "additionalProperties": false, "required": [ "posting_date", "fiscal_year_public_id", "lines" ], "properties": { "posting_date": { "type": "string", "format": "date" }, "fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "ledger_account_public_id", "side", "amount" ], "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } } } }, "FixedAssetPostingMutation": { "type": "object", "additionalProperties": false, "required": [ "operation", "public_id", "expected_revision", "before", "after" ], "properties": { "operation": { "type": "string", "enum": [ "create", "update", "remove" ] }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "expected_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "before": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetPosting" }, { "type": "null" } ] }, "after": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetPosting" }, { "type": "null" } ] } } }, "FixedAssetPostingMutations": { "type": "object", "additionalProperties": false, "required": [ "asset_depreciation", "asset_adjustment", "asset_disposal" ], "properties": { "asset_depreciation": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetPostingMutation" } }, "asset_adjustment": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetPostingMutation" } }, "asset_disposal": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetPostingMutation" } } } }, "FixedAssetDisposalResult": { "type": "object", "additionalProperties": false, "required": [ "book_value", "proceeds", "result" ], "properties": { "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "proceeds": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "result": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "FixedAssetSalesCorrection": { "type": "object", "additionalProperties": false, "required": [ "required", "assets" ], "properties": { "required": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "asset_public_id", "name", "sales_document_public_id", "sales_line_public_id", "choices" ], "properties": { "asset_public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "sales_document_public_id": { "$ref": "#/components/schemas/Ulid" }, "sales_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "choices": { "type": "array", "items": { "type": "string", "enum": [ "undo_sale", "relink" ] } } } } }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "name", "book_value", "disposal_result", "mutations" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "disposal_result": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetDisposalResult" }, { "type": "null" } ] }, "mutations": { "$ref": "#/components/schemas/FixedAssetPostingMutations" } } } } } }, "FixedAssetPurchaseCorrection": { "type": "object", "additionalProperties": false, "required": [ "required", "corrections" ], "properties": { "required": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "asset_public_id", "document_public_id", "line_public_id", "current_amount", "source_amount", "name" ], "properties": { "asset_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "current_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "source_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "name": { "type": "string" } } } }, "corrections": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "name", "book_value", "mutations" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "mutations": { "$ref": "#/components/schemas/FixedAssetPostingMutations" } } } }, "vat_required": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "line_public_id", "occurred_on", "available_cost_delta", "current_cost_delta", "name" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "occurred_on": { "type": "string", "format": "date" }, "available_cost_delta": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "current_cost_delta": { "type": [ "string", "null" ], "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "name": { "type": "string" } } } }, "vat_remainders": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "occurred_on", "cost_account_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "occurred_on": { "type": "string", "format": "date" }, "cost_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } } } }, "BankProposalCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "current_page", "last_page", "per_page", "matched_documents", "remaining_amount", "coverage" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankProposal" } }, "current_page": { "type": "integer", "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "enum": [ 10, 20 ] }, "searched_modules": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 2, "items": { "type": "string", "enum": [ "purchases", "sales" ] } }, "matched_documents": { "type": "integer", "minimum": 0 }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "references_limited", "related_sources_limited", "documents_have_more", "reference_limit", "related_source_limit" ], "properties": { "references_limited": { "type": "boolean" }, "related_sources_limited": { "type": "boolean" }, "documents_have_more": { "type": "boolean" }, "modules_limited": { "type": "boolean" }, "reference_limit": { "type": "integer", "const": 256 }, "related_source_limit": { "type": "integer", "const": 50 } } } } }, "BankProposal": { "type": "object", "additionalProperties": false, "required": [ "kind", "bank_entry_public_id", "target", "evidence", "available_amount", "currency_code", "input", "missing_fields", "warnings" ], "properties": { "kind": { "type": "string", "enum": [ "existing_leg", "settlement_input" ] }, "bank_entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "target": { "type": "object", "additionalProperties": false, "required": [ "type", "public_id", "document_public_id", "number", "contact" ], "properties": { "type": { "type": "string", "enum": [ "sales_settlement", "purchase_settlement", "sales_receipt", "sales_refund", "sales_customer_credit_refund", "purchase_payment", "purchase_supplier_refund", "purchase_payroll_refund" ] }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": [ "string", "null" ] }, "contact": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "public_id", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" } } } ] } } }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "source_path", "actual", "expected" ], "properties": { "code": { "type": "string", "enum": [ "reference_exact", "reference_token", "bank_account", "direction", "currency_equal", "currency_differs", "amount_equal", "amount_differs", "date_equal", "date_differs", "bank_booking_date" ] }, "source_path": { "type": "string" }, "actual": { "type": [ "string", "null" ] }, "expected": { "oneOf": [ { "type": [ "string", "null" ] }, { "type": "array", "items": { "type": "string" } } ] } } } }, "available_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "input": { "oneOf": [ { "type": "array", "maxItems": 0, "description": "No executable input when current source or write permission is unavailable." }, { "type": "object", "additionalProperties": false, "required": [ "link" ], "properties": { "link": { "type": "object", "additionalProperties": false, "required": [ "source_type", "source_public_id", "direction" ], "properties": { "source_type": { "type": "string", "enum": [ "sales_settlement", "purchase_settlement" ] }, "source_public_id": { "$ref": "#/components/schemas/Ulid" }, "direction": { "$ref": "#/components/schemas/BankDirection" }, "amount": { "type": "string" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "operation" ], "properties": { "operation": { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "enum": [ "sales_receipt", "sales_refund", "sales_customer_credit_refund", "purchase_payment", "purchase_supplier_refund", "purchase_payroll_refund" ] }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankProposedSettlementData" } } } } } ] }, "missing_fields": { "type": "array", "items": { "type": "string" }, "description": "Paths relative to link or operation (data.field), or permission. These are choices still required before the existing preview, not a complete domain-validation result." }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "reference_ambiguous", "already_linked", "bank_link_source_needs_review", "bank_link_capacity_exceeded" ] } } } }, "BankProposedSettlementData": { "type": "object", "additionalProperties": false, "required": [ "channel", "ledger_account_public_id" ], "description": "Partial typed input, not a valid posting request by itself. Only existing source identities and explicit evidence-based suggestions are present. Proposed operation and allocation amounts use the exact currency minor-unit scale (EUR 121.00, JPY 121, KWD 121.230), without rounding; a nonrepresentable amount is omitted and reported in missing_fields. Evidence, available_amount, remaining_amount and link amounts retain four-decimal precision. Complete missing_fields and use the relevant BankProcessingOperation contract for financial validation; no child command hashes.", "properties": { "channel": { "type": "string", "const": "bank" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "customer_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_date": { "type": "string", "format": "date" }, "payment_date": { "type": "string", "format": "date" }, "refund_date": { "type": "string", "format": "date" }, "amount": { "type": "string" }, "allocations": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "document_public_id" ], "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string" } } } } } }, "BankBatchEntryInput": { "type": "object", "additionalProperties": false, "required": [ "entry_public_id", "links", "operations" ], "properties": { "entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/BankLink" } }, "operations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/BankProcessingOperation" } } } }, "BankBatchPreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "entries" ], "description": "Distinct entry_public_id values; technical public IDs use their exact returned spelling and binary lookup. At most 100 operations across all entries. Ordered lists, never sparse or associative arrays. No cross-entry operation-reference.", "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/BankBatchEntryInput" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankBatchRequest": { "type": "object", "additionalProperties": false, "required": [ "entries", "state_hash" ], "properties": { "entries": { "$ref": "#/components/schemas/BankBatchPreviewRequest/properties/entries" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankBatchEntryPreview": { "type": "object", "additionalProperties": false, "required": [ "index", "operation_offset", "entry_public_id", "linked_amount", "remaining_amount", "warnings", "operations" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "operation_offset": { "type": "integer", "minimum": 0, "description": "Number of operations in preceding entries; add local operation index to obtain its command-global index for duplicate acknowledgements." }, "entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "linked_amount": { "type": "string" }, "remaining_amount": { "type": "string" }, "warnings": { "$ref": "#/components/schemas/BankProcessingPreview/properties/data/properties/warnings" }, "operations": { "$ref": "#/components/schemas/BankProcessingPreview/properties/data/properties/operations" } } }, "BankBatchPreview": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "state_hash", "entries" ], "properties": { "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "dependent_changes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyExchangeJournal" }, { "$ref": "#/components/schemas/CurrencyExchangeDependentJournal" } ] } }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/BankBatchEntryPreview" } } } } } }, "BankBatchResult": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankEntryDetail" } } } }, "BankTransferFx": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "conversion_mode", "rate" ], "properties": { "conversion_mode": { "type": "string", "const": "rate" }, "rate": { "type": "string", "maxLength": 40 } } }, { "type": "object", "additionalProperties": false, "required": [ "conversion_mode", "converted_base_amount" ], "properties": { "conversion_mode": { "type": "string", "const": "converted_amount" }, "converted_base_amount": { "type": "string", "maxLength": 32 } } } ], "description": "Explicit foreign-bank conversion on the corresponding bank date. Required when that bank account's currency differs from its administration's base currency; prohibited for a base-currency bank account. Rates and converted amounts must satisfy the existing FX engine." }, "BankTransferEdgeAmount": { "type": "object", "additionalProperties": false, "required": [ "configuration_public_id", "native_amount" ], "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "base_amounts": { "type": "array", "maxItems": 8, "items": { "type": "object", "additionalProperties": false, "required": [ "administration_public_id", "base_amount" ], "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "base_amount": { "type": "string", "maxLength": 32, "pattern": "^[0-9]+(?:\\.[0-9]+)?$" } } }, "description": "At most one value per administration for an actual endpoint of this route link. Applicable amounts are checked against the existing current-account route." } } }, "BankTransferInput": { "type": "object", "additionalProperties": false, "required": [ "source_bank_account_public_id", "target_bank_account_public_id", "clearing_ledger_account_public_id", "departure_date", "arrival_date", "departure_amount", "arrival_amount" ], "properties": { "source_bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "target_bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "clearing_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "departure_date": { "type": "string", "format": "date" }, "arrival_date": { "type": "string", "format": "date" }, "departure_amount": { "type": "string", "maxLength": 32, "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "arrival_amount": { "type": "string", "maxLength": 32, "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "departure_fx": { "$ref": "#/components/schemas/BankTransferFx" }, "arrival_fx": { "$ref": "#/components/schemas/BankTransferFx" }, "route_native_amount": { "type": "string", "maxLength": 32, "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/BankTransferEdgeAmount" }, "description": "Each configuration may occur only once and must belong to the actual route." } }, "description": "Own transfer from the operation's paying administration to another allowed bank account. Both real bank dates, both native amounts and an active base-currency-only balance-sheet clearing account in the paying administration are explicit. The two bank accounts must differ. No party/document is fabricated and no residual difference is automatically posted. Cross-administration transfers require route_native_amount and the existing permitted current-account route, posted on arrival_date; in one administration route_native_amount and non-empty route_configuration_public_ids/edge_amounts are not permitted. Route endpoint values must balance under the existing FX/current-account rules. The returned clearing_movement can be non-zero; a fully linked bank entry does not prove a zero clearing balance. Under active periodic cash valuation an own same-currency foreign transfer uses one departure_fx conversion and a matching FixedForeign other_receivables clearing account. arrival_fx and non-empty cash day_order are rejected. Arrival retains the exact original EUR principal proportionally to the actual amount received; signed differences remain visible, never automatically posted as costs or gain. Different-currency exchange uses Broker." }, "BankTransferUpdatePreviewRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "transfer" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "transfer": { "$ref": "#/components/schemas/BankTransferInput" } }, "description": "Complete replacement input, not a partial patch. BankTransferInput financial rules apply; exactly retained bank accounts in their original roles and the exact existing route may remain inactive. Newly selected banks/routes must be active; the clearing account has no inactive-retention exception. Child command hashes and undeclared fields are rejected." }, { "$ref": "#/components/schemas/BankTransferDeletePreviewRequest" } ] }, "BankTransferUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "transfer", "state_hash" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "transfer": { "$ref": "#/components/schemas/BankTransferInput" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "description": "Same complete replacement and retained-inactive contract as BankTransferUpdatePreviewRequest, plus the outer preview state_hash." }, "BankTransferResolvedEdgeAmount": { "type": "object", "additionalProperties": false, "required": [ "configuration_public_id", "denomination_currency_code", "native_amount", "base_amounts" ], "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" }, "base_amounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "administration_public_id", "base_amount" ], "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "base_amount": { "type": "string" } } } } }, "description": "Resolved current-account route amounts, separate from the originally submitted transfer.edge_amounts. Empty route list for a local transfer." }, "BankTransferJournalIdentity": { "type": "object", "additionalProperties": false, "required": [ "public_id", "administration_public_id", "entry_number", "role" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "entry_number": { "type": "integer", "minimum": 1 }, "role": { "type": "string", "enum": [ "departure", "arrival" ] } } }, "BankTransfer": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "deleted", "source_administration_public_id", "target_administration_public_id", "transfer", "edge_amounts", "journals" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "deleted": { "type": "boolean" }, "source_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "target_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "transfer": { "oneOf": [ { "$ref": "#/components/schemas/BankTransferInput" }, { "type": "null" } ] }, "edge_amounts": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BankTransferResolvedEdgeAmount" } }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/BankTransferJournalIdentity" } }, "cash_contract_version": { "type": "integer", "enum": [ 1, 2 ], "description": "Version 2 is the own same-currency periodic source contract. Its deletion requires the operation=delete preview proof." }, "provider_payout": { "type": "object", "additionalProperties": false, "required": [ "reference", "fee_settlement_public_id" ], "properties": { "reference": { "type": [ "string", "null" ] }, "fee_settlement_public_id": { "type": [ "string", "null" ] } } } }, "description": "Only current owned journal identities are exposed. After deletion, target_administration_public_id, transfer and edge_amounts are null and journals is empty; identity, revision, source administration and deleted=true remain. No historical financial snapshot or implicit restoration." }, "BankTransferResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankTransfer" } } }, "BankTransferIdentityResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 } } } } }, "BankTransferPreviewJournal": { "type": "object", "additionalProperties": false, "required": [ "posting_date", "currency_code", "state_hash", "carrying_dependent", "lines", "positions_after", "administration_public_id", "entry_number", "role" ], "properties": { "before": { "$ref": "#/components/schemas/CurrencyExchangeJournal" }, "before_label": { "type": "string" }, "after_label": { "type": "string" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "description": { "type": "string" }, "posting_date": { "type": "string", "format": "date" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "carrying_dependent": { "type": "boolean" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/JournalFxPreviewLine" } }, "positions_after": { "oneOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FxPosition" } }, { "type": "array", "maxItems": 0 } ], "description": "Native account positions keyed by account public ID; the existing preview serializer returns an empty array when no native positions exist." }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "entry_number": { "type": "integer", "minimum": 1 }, "role": { "type": "string", "enum": [ "departure", "arrival", "periodic_valuation" ] }, "heading": { "type": "string" }, "administration_name": { "type": "string" } } }, "BankTransferUpdatePreviewResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "public_id", "expected_revision", "state_hash", "unchanged", "transfer", "clearing_currency_code", "clearing_movement", "edge_amounts", "journals" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "unchanged": { "type": "boolean" }, "transfer": { "$ref": "#/components/schemas/BankTransferInput" }, "clearing_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "clearing_movement": { "type": "string" }, "edge_amounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankTransferResolvedEdgeAmount" } }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/BankTransferPreviewJournal" } }, "operation": { "const": "delete" }, "clearing_native_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "clearing_native_movement": { "type": "string", "description": "Signed original-principal difference in the actual bank currency, separate from the EUR movement." }, "removed_journals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "entry_number", "role", "posting_date" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "entry_number": { "type": "integer", "minimum": 1 }, "role": { "enum": [ "departure", "arrival" ] }, "posting_date": { "type": "string", "format": "date" } } } } } } } }, "BankSourceType": { "type": "string", "enum": [ "sales_settlement", "purchase_settlement", "manual_journal", "rekening_courant", "bank_transfer", "loan", "vat_return_payment", "investment_settlement", "currency_exchange", "bank_owner_movement", "bank_tax_movement", "bank_balance_movement" ], "description": "investment_settlement identifies a posted Broker cash settlement. currency_exchange identifies a complete proved Broker currency-exchange source and exposes only its actual cash leg on the exact Bank account. Both require investments:read in addition to Banking permissions. Claims and valuations are not Bank cash legs. Linking creates no financial posting." }, "BankDirection": { "type": "string", "enum": [ "CRDT", "DBIT" ] }, "BankRuleOperation": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "sales_receipt" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "sales_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "sales_customer_credit_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "sales_document" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string", "maxLength": 100 }, "vat_context": { "type": "object", "additionalProperties": false, "required": [], "properties": { "region": { "type": "string", "maxLength": 100 }, "supply_type": { "type": "string", "maxLength": 100 }, "customer_type": { "type": "string", "maxLength": 100 } } }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [], "properties": { "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "maxLength": 100 }, "margin_method": { "type": "string", "maxLength": 100 }, "no_vat_reason": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, "maxItems": 500 }, "direct_settlement": { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "purchase_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "purchase_supplier_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "purchase_payroll_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "purchase_document" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string", "maxLength": 100 }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [], "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "maxLength": 100 }, "margin_method": { "type": "string", "maxLength": 100 }, "deductible_percentage": { "oneOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "string", "pattern": "^\\d{1,3}(?:\\.\\d{1,4})?$" } ], "description": "0..100 with at most 4 decimals; no exponent or non-finite values." }, "non_deductible_treatment": { "type": "string", "maxLength": 100 }, "foreign_vat_country_code": { "type": "string", "maxLength": 100 }, "foreign_vat_disposition": { "type": "string", "maxLength": 100 } } }, "maxItems": 500 }, "payment": { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "manual_journal" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [], "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "side": { "type": "string", "maxLength": 100 } } }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "bank_transfer" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "source_bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "target_bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "clearing_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "loan" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "loan_public_id": { "$ref": "#/components/schemas/Ulid" }, "kind": { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "vat_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "vat_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "type": "string", "maxLength": 100 }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" }, "maxItems": 500 } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "owner_withdrawal" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "receiving_administration_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "payer_contact_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "route_configuration_public_ids": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ] }, "maxItems": 500 }, { "type": "null" }, { "const": "" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "owner_contribution" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "receiving_administration_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "payer_contact_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "route_configuration_public_ids": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ] }, "maxItems": 500 }, { "type": "null" }, { "const": "" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "tax_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "kind": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "bank_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "tax_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "kind": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "bank_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "balance_liability_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "kind": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "bank_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "balance_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "balance_dividend_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "kind": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "bank_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "balance_dividend_tax_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "kind": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "bank_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "provider_payout" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "channel": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\x00-\\x1F\\x7F]*$" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "receiving_administration_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "payer_contact_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." }, "route_configuration_public_ids": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "string", "pattern": "^[ \\t\\n\\r\\x00\\x0B]*$" } ] }, "maxItems": 500 }, { "type": "null" }, { "const": "" } ], "description": "Known null and exact empty-string choices are omitted. Existing Laravel validation accepts trim-blank scalar strings and preserves them; route list items likewise retain blank strings, never null. This partial storage contract does not validate a complete financial command." } } }, { "type": "array", "maxItems": 0 } ] } } } ], "description": "Partial reusable choices only, never a complete bookable financial instruction. All currently accepted operation types are documented. Owner withdrawals, owner contributions and provider payouts retain the existing generic settlement storage boundary, including payer_contact_public_id; their complete financial inputs are not reusable aliases. No amount, date, FX evidence, source claim, state hash or acknowledgement is stored. Empty data is represented as an empty object or empty array; choosing a rule never posts automatically. For the newly documented variants, known null or empty-string choices are omitted by the existing template validator; unknown fields are rejected even when empty." }, "BankRuleInput": { "type": "object", "additionalProperties": false, "required": [ "name", "bank_account_public_id", "direction", "active", "operation", "expected_revision" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "direction": { "enum": [ "CRDT", "DBIT" ] }, "counterparty_name_contains": { "type": [ "string", "null" ], "maxLength": 255 }, "counterparty_account": { "type": [ "string", "null" ], "maxLength": 100 }, "description_contains": { "type": [ "string", "null" ], "maxLength": 255 }, "active": { "type": "boolean" }, "operation": { "$ref": "#/components/schemas/BankRuleOperation" }, "expected_revision": { "type": "integer", "minimum": 0 } }, "description": "At least one nonempty counterparty_name_contains, counterparty_account or description_contains required. Counterparty name uses case-insensitive substring matching without trimming, whitespace or accent normalization. Account and description retain literal case-sensitive matching including spaces. All supplied criteria must match the same eligible CAMT detail; name and account must match the same direction-appropriate party. Description-only rules may also match the entry description. Own account excluded. Omitting the optional name condition is equivalent to null, including command retries. A deleted bank account may remain on an existing rule, but must be changed before reuse." }, "BankRule": { "type": "object", "additionalProperties": false, "required": [ "public_id", "name", "bank_account_public_id", "bank_account_name", "account_available", "direction", "counterparty_name_contains", "counterparty_account", "description_contains", "active", "revision", "operation" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_account_name": { "type": [ "string", "null" ] }, "account_available": { "type": "boolean" }, "direction": { "enum": [ "CRDT", "DBIT" ] }, "counterparty_name_contains": { "type": [ "string", "null" ] }, "counterparty_account": { "type": [ "string", "null" ] }, "description_contains": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1 }, "operation": { "oneOf": [ { "$ref": "#/components/schemas/BankRuleOperation" }, { "type": "null" } ], "description": "Null without current source, participant and module read access, including write-only tokens." } } }, "BankRuleResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankRule" } } }, "BankRuleCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankRule" } }, "links": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } } } }, "BankRuleSuggestion": { "type": "object", "additionalProperties": false, "required": [ "kind", "bank_entry_public_id", "rule_public_id", "revision", "name", "evidence", "input" ], "properties": { "kind": { "const": "rule_input" }, "bank_entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "rule_public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer" }, "name": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "path", "value" ], "properties": { "path": { "type": "string" }, "value": { "type": "string" } } } }, "input": { "type": "object", "additionalProperties": false, "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/BankRuleOperation" } } } } }, "BankRuleSuggestionPage": { "type": "object", "additionalProperties": false, "required": [ "data", "total", "current_page", "last_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankRuleSuggestion" } }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" } }, "description": "All usable matches ordered by public_id, 20 per page. No hidden priority, automatic choice or posting." }, "BankRuleField": { "type": "object", "additionalProperties": false, "required": [ "path", "label", "options", "json", "decimal", "search_url" ], "properties": { "path": { "type": "string" }, "label": { "type": "string" }, "options": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "maxItems": 0 }, { "type": "null" } ] }, "json": { "type": "boolean" }, "decimal": { "type": "boolean" }, "search_url": { "type": [ "string", "null" ], "description": "Web contact search URL; API clients can use the existing scoped contact API." } } }, "BankRuleFormData": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "fields", "operation" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/BankRuleField" } }, "operation": { "$ref": "#/components/schemas/BankRuleOperation" } } } } }, "BankAccountInput": { "type": "object", "additionalProperties": false, "required": [ "name", "currency_code", "ledger_account_public_id", "starts_on", "active", "expected_revision" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "identity_type": { "type": "string", "enum": [ "iban", "other", "none" ] }, "identity": { "type": [ "string", "null" ], "maxLength": 42, "description": "Valid IBAN when identity_type=iban; other identifiers at most 35 characters. Control characters rejected; original spelling is preserved." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "starts_on": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "expected_revision": { "type": "integer", "minimum": 0 }, "account_kind": { "type": "string", "enum": [ "cash_account", "payment_provider" ] }, "provider_fee_ledger_account_public_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "allOf": [ { "if": { "required": [ "account_kind" ], "properties": { "account_kind": { "const": "payment_provider" } } }, "then": { "properties": { "identity_type": { "const": "none" }, "identity": { "type": "null" } } }, "else": { "required": [ "identity_type", "identity" ], "properties": { "identity_type": { "enum": [ "iban", "other" ] }, "identity": { "type": "string", "minLength": 1 } } } } ] }, "BankAccountCreateInput": { "type": "object", "additionalProperties": false, "required": [ "name", "currency_code", "starts_on", "active", "expected_revision" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "identity_type": { "type": "string", "enum": [ "iban", "other", "none" ] }, "identity": { "type": [ "string", "null" ], "maxLength": 42, "description": "Valid IBAN when identity_type=iban; other identifiers at most 35 characters. Control characters rejected; original spelling is preserved." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "starts_on": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "expected_revision": { "type": "integer", "minimum": 0 }, "new_ledger_account": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "maxLength": 10, "pattern": "^[A-Za-z0-9]+$" }, "reporting_classification_code": { "type": "string", "enum": [ "bank", "savings_deposits", "other_receivables" ], "description": "Existing explicit classification alternative: bank or savings_deposits for cash_account, other_receivables for payment_provider. Mutually exclusive with account_type; purpose compatibility is checked by the existing input policy." }, "account_type": { "type": "string", "enum": [ "bank", "savings_deposits", "broker_cash", "payment_provider" ], "description": "Explicit creation purpose. bank creates a bank ledger with BLimBanRba; savings_deposits creates a savings ledger with BLimBanSpa; broker_cash creates a bank-classified money ledger with BLimBanBel. Choose exactly one account_type or the existing reporting_classification_code representation. payment_provider creates an other_receivables ledger with BVorOvrOvk and requires account_kind=payment_provider; other purposes require cash_account." } }, "oneOf": [ { "required": [ "account_type" ], "not": { "required": [ "reporting_classification_code" ] } }, { "required": [ "reporting_classification_code" ], "not": { "required": [ "account_type" ] } } ] }, "account_kind": { "type": "string", "enum": [ "cash_account", "payment_provider" ] }, "provider_fee_ledger_account_public_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "oneOf": [ { "required": [ "ledger_account_public_id" ], "not": { "required": [ "new_ledger_account" ] } }, { "required": [ "new_ledger_account" ], "not": { "required": [ "ledger_account_public_id" ] } } ], "description": "Creation only: exactly one existing ledger_account_public_id or new_ledger_account. A new ledger requires ledger_accounts:write as well as banking:write, including replay. Its name and currency are copied from the bank input; standard ledger name/code normalization applies. Account type is explicit. RGS 3.8 follows the chosen account type (bank BLimBanRba, savings_deposits BLimBanSpa, broker_cash BLimBanBel, payment_provider BVorOvrOvk), not the ledger number. broker_cash represents the approved ordinary broker money account under liquid assets and keeps the existing bank ledger classification. No licence question or broker-only eligibility flag is introduced. Ledger and bank account plus audits and command are created atomically, without financial postings. An occupied code fails with ledger_account_code_already_exists (409); no alternate code is silently chosen. active and currency_code remain explicit required API fields; form defaults are only proposals. payment_provider is only compatible with account_kind=payment_provider and uses other_receivables; ordinary cash_account uses bank/savings_deposits/broker_cash. The existing reporting_classification_code alternative supports other_receivables only for a provider, and bank/savings_deposits for cash_account. These are existing eligibility checks, not interchangeable purposes.", "allOf": [ { "if": { "required": [ "account_kind" ], "properties": { "account_kind": { "const": "payment_provider" } } }, "then": { "properties": { "identity_type": { "const": "none" }, "identity": { "type": "null" } } }, "else": { "required": [ "identity_type", "identity" ], "properties": { "identity_type": { "enum": [ "iban", "other" ] }, "identity": { "type": "string", "minLength": 1 } } } } ] }, "BankAccount": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "name", "identity_type", "identity", "currency_code", "ledger_account_public_id", "starts_on", "active", "account_kind", "provider_fee_ledger_account_public_id" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 100 }, "identity_type": { "type": "string", "enum": [ "iban", "other", "none" ] }, "identity": { "type": [ "string", "null" ], "maxLength": 42, "description": "Valid IBAN when identity_type=iban; other identifiers at most 35 characters. Control characters rejected; original spelling is preserved." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "starts_on": { "type": "string", "format": "date" }, "active": { "type": "boolean" }, "account_kind": { "type": "string", "enum": [ "cash_account", "payment_provider" ] }, "provider_fee_ledger_account_public_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } }, "BankAccountResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankAccount" } } }, "BankNextLink": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } }, "BankAccountCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } }, "links": { "$ref": "#/components/schemas/BankNextLink" } } }, "BankFormData": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "account", "ledger_accounts", "currency_codes", "routing_locked", "routing_lock_reason", "can_delete", "delete_lock_reason", "creation_defaults", "new_ledger_options" ], "properties": { "account": { "anyOf": [ { "$ref": "#/components/schemas/BankAccount" }, { "type": "null" } ] }, "ledger_accounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name", "currency_code", "eligible", "current" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "currency_code": { "type": "string" }, "eligible": { "type": "boolean" }, "current": { "type": "boolean" }, "account_kinds": { "type": "array", "items": { "type": "string", "enum": [ "cash_account", "payment_provider" ] } } } } }, "currency_codes": { "type": "array", "items": { "type": "string" } }, "routing_locked": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "routing_lock_reason": { "type": [ "string", "null" ], "enum": [ "settlement", "transfer", "import", "broker", "vat", "tax", "balance", "owner", null ], "description": "settlement: existing provider or Mollie-linked financial use; transfer: active own-transfer; import: imported history; broker: live Broker use; vat: active VAT payments; tax: active corporate-income-tax movements; balance: active balance-liability or dividend movements; owner: active private withdrawals or contributions; null: not locked. Form-data priority: settlement, transfer, import, broker, vat, tax, balance, owner. Routing import history means statements; entries alone do not set the routing reason." }, "delete_lock_reason": { "type": [ "string", "null" ], "enum": [ "settlement", "transfer", "import", "broker", "vat", "tax", "balance", "owner", null ], "description": "settlement: existing provider or Mollie-linked financial use; transfer: active own-transfer; import: imported history; broker: live Broker use; vat: active VAT payments; tax: active corporate-income-tax movements; balance: active balance-liability or dividend movements; owner: active private withdrawals or contributions; null: not locked. Form-data priority: settlement, transfer, import, broker, vat, tax, balance, owner. Deletion import history means statements or entries. This form-data reason is not a guarantee of the first exception in the delete command." }, "creation_defaults": { "type": "object", "additionalProperties": false, "required": [ "active", "currency_code" ], "properties": { "active": { "type": "boolean", "const": true }, "currency_code": { "type": "string" } }, "description": "Fresh-create UI defaults only: active and the administration currency. Never overwrite persisted or restored input." }, "new_ledger_options": { "type": "object", "additionalProperties": false, "required": [ "bank", "savings_deposits", "broker_cash" ], "properties": { "bank": { "type": "object", "additionalProperties": false, "required": [ "suggested_code", "rgs" ], "properties": { "suggested_code": { "type": [ "string", "null" ] }, "rgs": { "type": "object", "additionalProperties": false, "required": [ "version", "reference_code" ], "properties": { "version": { "type": "string", "const": "3.8" }, "reference_code": { "type": "string" } } } } }, "savings_deposits": { "type": "object", "additionalProperties": false, "required": [ "suggested_code", "rgs" ], "properties": { "suggested_code": { "type": [ "string", "null" ] }, "rgs": { "type": "object", "additionalProperties": false, "required": [ "version", "reference_code" ], "properties": { "version": { "type": "string", "const": "3.8" }, "reference_code": { "type": "string" } } } } }, "broker_cash": { "type": "object", "additionalProperties": false, "required": [ "suggested_code", "rgs" ], "properties": { "suggested_code": { "type": [ "string", "null" ] }, "rgs": { "type": "object", "additionalProperties": false, "required": [ "version", "reference_code" ], "properties": { "version": { "type": "string", "const": "3.8" }, "reference_code": { "type": "string" } } } } }, "payment_provider": { "type": "object", "additionalProperties": false, "required": [ "suggested_code", "rgs" ], "properties": { "suggested_code": { "type": [ "string", "null" ] }, "rgs": { "type": "object", "additionalProperties": false, "required": [ "version", "reference_code" ], "properties": { "version": { "type": "string", "const": "3.8" }, "reference_code": { "type": "string" } } } } } }, "description": "Read-only unreserved proposals: payment accounts 1100-1129, savings accounts 1130-1159, broker money accounts 1160-1199. Each uses only its own proposal range. All occupied codes, including inactive accounts, are skipped. Null means no free proposal; explicitly chosen codes are not restricted to these ranges. Existing accounts are never renumbered." }, "provider_fee_available": { "type": "boolean" }, "provider_fee_accounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } } } } } } }, "BankRevisionRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } }, "BankLink": { "type": "object", "additionalProperties": false, "required": [ "source_type", "source_public_id", "direction", "amount" ], "properties": { "source_type": { "$ref": "#/components/schemas/BankSourceType" }, "source_public_id": { "$ref": "#/components/schemas/Ulid" }, "direction": { "$ref": "#/components/schemas/BankDirection" }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(?:\\.[0-9]{1,12})?$", "description": "Strictly positive exact cash amount in account currency, with up to twelve decimal places; the explicit direction supplies its sign. The server controls storage precision and preserves legacy source fingerprints." } } }, "BankLinksPreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "links" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/BankLink" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankLinksRequest": { "type": "object", "additionalProperties": false, "required": [ "links", "state_hash" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/BankLink" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankLinkWarning": { "type": "object", "additionalProperties": false, "required": [ "code", "index", "bank_date", "booking_dates" ], "properties": { "code": { "type": "string", "const": "bank_link_date_differs" }, "index": { "type": "integer", "minimum": 0 }, "bank_date": { "type": [ "string", "null" ] }, "booking_dates": { "type": "array", "items": { "type": "string" } } } }, "BankLinksPreview": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "entry_public_id", "linked_amount", "remaining_amount", "warnings", "state_hash", "links" ], "properties": { "entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "linked_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/BankLinkWarning" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/BankLink" } } } } } }, "BankEntry": { "type": "object", "additionalProperties": false, "required": [ "public_id", "bank_account_public_id", "amount", "currency_code", "direction", "booking_date", "value_date", "booking_date_kind", "value_date_kind", "description", "source_status", "source_status_type", "reversal", "review_flags", "linked_amount", "remaining_amount", "link_status", "summary" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "currency_code": { "type": "string" }, "direction": { "$ref": "#/components/schemas/BankDirection" }, "booking_date": { "$ref": "#/components/schemas/BankSourceDate" }, "value_date": { "$ref": "#/components/schemas/BankSourceDate" }, "booking_date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "value_date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "description": { "type": [ "string", "null" ] }, "source_status": { "type": [ "string", "null" ] }, "source_status_type": { "type": [ "string", "null" ] }, "reversal": { "type": "boolean" }, "review_flags": { "type": "array", "items": { "type": "string" }, "description": "Current actionable warnings derived from immutable import diagnostics, identically for preview and stored entries. detail_amounts_incomplete is omitted only for exactly one detail with neither amount nor transaction_amount and no batch evidence. Other warnings remain unchanged. Source amounts, stored diagnostics and duplicate fingerprints are not rewritten." }, "linked_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "link_status": { "type": "string", "enum": [ "unlinked", "partial", "linked", "needs_review" ] }, "summary": { "$ref": "#/components/schemas/BankEntrySummary" } } }, "BankEntrySummary": { "type": "object", "additionalProperties": false, "description": "Locale-neutral display facts derived from existing source evidence. Never used for hashes, duplicate matching or financial processing. Only one detail with exactly one direction-appropriate party supplies a counterparty; multiple details remain separate in source evidence.", "required": [ "detail_count", "mixed_directions", "counterparty", "description", "remittance", "additional_information" ], "properties": { "detail_count": { "type": "integer", "minimum": 0 }, "mixed_directions": { "type": "boolean" }, "counterparty": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "role", "name", "account" ], "properties": { "role": { "type": "string", "enum": [ "debtor", "creditor" ] }, "name": { "type": [ "string", "null" ] }, "account": { "type": [ "string", "null" ] } } } ] }, "description": { "type": [ "string", "null" ] }, "remittance": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "enum": [ "unstructured", "structured_reference", "structured_additional" ] }, "value": { "type": "string" } } } }, "additional_information": { "type": [ "string", "null" ] } } }, "BankSourceDate": { "type": [ "string", "null" ], "description": "Exact parser-validated CAMT date or datetime text, retaining every fractional digit and the supplied timezone spelling (including no timezone). Never a reformatted DateTime projection. Null means absent. Period bounds are datetime text." }, "BankSourceDateKind": { "type": [ "string", "null" ], "enum": [ "date", "datetime", null ], "description": "The received XML choice: date for Dt, datetime for DtTm; null means no source kind. Midnight never implies date-only evidence." }, "BankSourceEvidence": { "description": "Preserved CAMT source evidence, including identifiers, counterparties, batch metadata and charge details where supplied. Source facts are not a financial posting or an automatically selected counterparty.", "type": [ "object", "array", "null" ] }, "BankEntryDetail": { "type": "object", "additionalProperties": false, "required": [ "public_id", "bank_account_public_id", "amount", "currency_code", "direction", "booking_date", "value_date", "booking_date_kind", "value_date_kind", "description", "source_status", "source_status_type", "reversal", "review_flags", "linked_amount", "remaining_amount", "link_status", "reference", "servicer_reference", "transaction_code", "batches", "details", "charges", "links", "summary" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "currency_code": { "type": "string" }, "direction": { "$ref": "#/components/schemas/BankDirection" }, "booking_date": { "$ref": "#/components/schemas/BankSourceDate" }, "value_date": { "$ref": "#/components/schemas/BankSourceDate" }, "booking_date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "value_date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "description": { "type": [ "string", "null" ] }, "source_status": { "type": [ "string", "null" ] }, "source_status_type": { "type": [ "string", "null" ] }, "reversal": { "type": "boolean" }, "review_flags": { "type": "array", "items": { "type": "string" }, "description": "Current actionable warnings derived from immutable import diagnostics, identically for preview and stored entries. detail_amounts_incomplete is omitted only for exactly one detail with neither amount nor transaction_amount and no batch evidence. Other warnings remain unchanged. Source amounts, stored diagnostics and duplicate fingerprints are not rewritten." }, "linked_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "link_status": { "type": "string", "enum": [ "unlinked", "partial", "linked", "needs_review" ] }, "reference": { "type": [ "string", "null" ] }, "servicer_reference": { "type": [ "string", "null" ] }, "transaction_code": { "$ref": "#/components/schemas/BankSourceEvidence" }, "batches": { "type": "array", "items": { "$ref": "#/components/schemas/BankSourceEvidence" } }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/BankSourceEvidence" } }, "charges": { "$ref": "#/components/schemas/BankSourceEvidence" }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "source_type", "source_public_id", "direction", "amount", "current" ], "properties": { "source_type": { "$ref": "#/components/schemas/BankSourceType" }, "source_public_id": { "$ref": "#/components/schemas/Ulid" }, "direction": { "$ref": "#/components/schemas/BankDirection" }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(?:\\.[0-9]{1,4})?$", "description": "Strictly positive amount in account currency; the explicit direction supplies its sign." }, "current": { "type": "boolean" } } } }, "summary": { "$ref": "#/components/schemas/BankEntrySummary" } } }, "BankEntryResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankEntryDetail" } } }, "BankEntryCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankEntry" } }, "links": { "$ref": "#/components/schemas/BankNextLink" } } }, "BankSourcePagination": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "page", "last" ], "properties": { "page": { "type": "string" }, "last": { "type": "boolean" } } }, { "type": "null" } ] }, "BankImport": { "type": "object", "additionalProperties": false, "required": [ "public_id", "file_hash", "format", "message_id", "source_created_at", "pagination", "has_source_file", "created_at" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "file_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "format": { "type": "string" }, "message_id": { "type": [ "string", "null" ] }, "source_created_at": { "type": [ "string", "null" ] }, "pagination": { "$ref": "#/components/schemas/BankSourcePagination" }, "has_source_file": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } } }, "BankImportResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankImport" } } }, "BankImportCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankImport" } }, "links": { "$ref": "#/components/schemas/BankNextLink" } } }, "BankBalanceEvidence": { "type": "object", "description": "Original CAMT balance projection. type distinguishes opening/closing and other source balances; date_kind preserves date versus datetime evidence.", "properties": { "type": { "type": "string" }, "date": { "$ref": "#/components/schemas/BankSourceDate" }, "date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "currency": { "type": "string" }, "source_code": { "type": "string", "description": "Original ISO CAMT balance code. PRCD is previous closing, OPBD opening and CLBD closing. Absent on unverified older metadata." } } }, "BankStatement": { "type": "object", "additionalProperties": false, "required": [ "position", "bank_account_public_id", "reference", "account_evidence", "balances", "from_date", "to_date" ], "properties": { "position": { "type": "integer", "minimum": 0 }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "reference": { "type": [ "string", "null" ] }, "account_evidence": { "$ref": "#/components/schemas/BankSourceEvidence" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/BankBalanceEvidence" } }, "from_date": { "$ref": "#/components/schemas/BankSourceDate" }, "to_date": { "$ref": "#/components/schemas/BankSourceDate" } } }, "BankImportDetail": { "type": "object", "additionalProperties": false, "required": [ "data", "statements", "links" ], "properties": { "data": { "$ref": "#/components/schemas/BankImport" }, "statements": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatement" } }, "links": { "$ref": "#/components/schemas/BankNextLink" } } }, "BankImportMapping": { "type": "object", "additionalProperties": false, "required": [ "statement", "bank_account_public_id", "expected_revision" ], "properties": { "statement": { "type": "integer", "minimum": 0 }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "BankImportInput": { "type": "object", "additionalProperties": false, "required": [ "mappings" ], "properties": { "mappings": { "type": "array", "items": { "$ref": "#/components/schemas/BankImportMapping" } }, "choices": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 64 }, "description": "Keys are statement:entry positions returned by the preview. Value is new or an exact candidate target (existing public ID or incoming:statement:position). Ambiguous matches require an explicit choice. Different source facts cannot overwrite a stored entry." }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankImportConfirmInput": { "type": "object", "additionalProperties": false, "required": [ "mappings", "state_hash" ], "properties": { "mappings": { "type": "array", "items": { "$ref": "#/components/schemas/BankImportMapping" } }, "choices": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 64 }, "description": "Keys are statement:entry positions returned by the preview. Value is new or an exact candidate target (existing public ID or incoming:statement:position). Ambiguous matches require an explicit choice. Different source facts cannot overwrite a stored entry." }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankFileInspection": { "type": "object", "additionalProperties": false, "required": [ "file_hash", "format", "message_id", "created_at", "source_pagination", "statements" ], "properties": { "file_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "format": { "type": "string" }, "message_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "source_pagination": { "$ref": "#/components/schemas/BankSourcePagination" }, "statements": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "statement", "reference", "account", "from_date", "to_date", "entry_count", "balances" ], "properties": { "statement": { "type": "integer", "minimum": 0 }, "reference": { "type": [ "string", "null" ] }, "account": { "$ref": "#/components/schemas/BankSourceEvidence" }, "from_date": { "$ref": "#/components/schemas/BankSourceDate" }, "to_date": { "$ref": "#/components/schemas/BankSourceDate" }, "entry_count": { "type": "integer", "minimum": 0 }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/BankBalanceEvidence" } } } } } } }, "BankInspectionResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankFileInspection" } } }, "BankImportPreviewRow": { "type": "object", "additionalProperties": false, "required": [ "key", "statement", "position", "source", "duplicate", "candidate_count", "identifier_missing", "summary" ], "properties": { "key": { "type": "string" }, "statement": { "type": "integer", "minimum": 0 }, "position": { "type": "integer", "minimum": 0 }, "source": { "$ref": "#/components/schemas/BankSourceEvidence", "description": "Source facts with current actionable review_flags, using the same assessment as BankEntry.review_flags. Stored import diagnostics, source amounts and duplicate fingerprints remain unchanged." }, "duplicate": { "type": [ "string", "null" ] }, "candidate_count": { "type": "integer", "minimum": 0 }, "identifier_missing": { "type": "boolean" }, "summary": { "$ref": "#/components/schemas/BankEntrySummary" } } }, "BankImportPreview": { "type": "object", "additionalProperties": false, "required": [ "file_hash", "format", "message_id", "created_at", "source_pagination", "statements", "state_hash", "existing_import_public_id", "rows", "pagination" ], "properties": { "file_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "format": { "type": "string" }, "message_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "source_pagination": { "$ref": "#/components/schemas/BankSourcePagination" }, "statements": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "statement", "reference", "account", "from_date", "to_date", "entry_count", "balances" ], "properties": { "statement": { "type": "integer", "minimum": 0 }, "reference": { "type": [ "string", "null" ] }, "account": { "$ref": "#/components/schemas/BankSourceEvidence" }, "from_date": { "$ref": "#/components/schemas/BankSourceDate" }, "to_date": { "$ref": "#/components/schemas/BankSourceDate" }, "entry_count": { "type": "integer", "minimum": 0 }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/BankBalanceEvidence" } } } } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "existing_import_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BankImportPreviewRow" } }, "pagination": { "type": "object", "additionalProperties": false, "required": [ "page", "per_page", "total" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "const": 50 }, "total": { "type": "integer", "minimum": 0 } } } } }, "BankImportCandidatePage": { "type": "object", "additionalProperties": false, "required": [ "state_hash", "total", "page", "per_page", "data" ], "properties": { "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "const": 20 }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "target", "same_facts", "source", "incoming_position", "summary" ], "properties": { "target": { "type": "string" }, "same_facts": { "type": "boolean" }, "incoming_position": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "statement", "position" ], "properties": { "statement": { "type": "integer", "minimum": 0 }, "position": { "type": "integer", "minimum": 0 } } } ] }, "source": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "amount", "currency_code", "direction", "booking_date", "value_date", "booking_date_kind", "value_date_kind", "description", "reference", "servicer_reference" ], "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "currency_code": { "type": "string" }, "direction": { "$ref": "#/components/schemas/BankDirection" }, "booking_date": { "$ref": "#/components/schemas/BankSourceDate" }, "value_date": { "$ref": "#/components/schemas/BankSourceDate" }, "booking_date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "value_date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "description": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "servicer_reference": { "type": [ "string", "null" ] } } }, { "type": "array", "maxItems": 0 } ], "description": "Human-readable current source facts for comparison. Incoming candidates identify their statement/position; an existing source removed concurrently may have no remaining facts (empty array). Confirmation rechecks the complete source state." }, "summary": { "$ref": "#/components/schemas/BankEntrySummary" } } } } } }, "BankImportPreviewResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/BankImportPreview" }, { "$ref": "#/components/schemas/BankImportCandidatePage" } ] } } }, "BankImportDeletionPreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "file_only" ], "properties": { "file_only": { "type": "boolean" } } }, "BankImportDeletionRequest": { "type": "object", "additionalProperties": false, "required": [ "file_only", "state_hash" ], "properties": { "file_only": { "type": "boolean" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankImportDeletionPreview": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "public_id", "state_hash", "has_source_file", "statement_count", "entry_count", "shared_entry_count", "linked_entry_count" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "has_source_file": { "type": "boolean" }, "statement_count": { "type": "integer", "minimum": 0 }, "entry_count": { "type": "integer", "minimum": 0 }, "shared_entry_count": { "type": "integer", "minimum": 0 }, "linked_entry_count": { "type": "integer", "minimum": 0 } } } } }, "BankFinancialCandidate": { "type": "object", "additionalProperties": false, "required": [ "bank_leg_id", "source_type", "source_public_id", "bank_account_public_id", "direction", "currency_code", "amount", "available_amount", "unavailable_reason", "dates", "journals", "source_details" ], "properties": { "bank_leg_id": { "type": "string" }, "source_type": { "$ref": "#/components/schemas/BankSourceType" }, "source_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "direction": { "$ref": "#/components/schemas/BankDirection" }, "currency_code": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "available_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "unavailable_reason": { "type": [ "string", "null" ] }, "dates": { "type": "array", "items": { "type": "string" } }, "journals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "number", "date", "description" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ] } } } }, "source_details": { "type": "array", "items": { "type": "string" }, "description": "Read-only contact and document labels for sources owned by this administration. All allocated documents are retained. Empty for cross-administration sources; local journal visibility never grants access to remote source metadata. Not accepted in financial command input." } } }, "BankFinancialCandidateCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "current_page", "last_page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankFinancialCandidate" } }, "current_page": { "type": "integer", "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 50 }, "total": { "type": "integer", "minimum": 0 } } }, "BankReconciliation": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "bank_account_public_id", "ledger_account_public_id", "currency_code", "as_of_date", "bank_balance", "ledger_balance", "ledger_projection", "bank_balance_candidates", "difference", "balances_equal", "coverage", "balance_issues", "entries", "reconciled" ], "properties": { "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string" }, "as_of_date": { "type": "string", "format": "date" }, "bank_balance": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, { "type": "null" } ] }, "ledger_balance": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Exact bank-currency cash derived from the journals. Legacy source spelling remains four decimals; proved exact cash can retain twelve. For administration-currency cash, ledger_projection separates the cent ledger from actual cash." }, "ledger_projection": { "description": "Administration-currency cent projection and its proved native-minus-ledger rounding difference. Null when no exact administration-currency cash evidence applies. This read does not book or write off the difference.", "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "currency_code", "ledger_balance", "rounding_difference" ], "properties": { "currency_code": { "type": "string" }, "ledger_balance": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "rounding_difference": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } } } ] }, "bank_balance_candidates": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "date_kind", "amount", "currency_code", "day_end_proven" ], "properties": { "date": { "type": "string" }, "date_kind": { "$ref": "#/components/schemas/BankSourceDateKind" }, "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "currency_code": { "type": "string" }, "day_end_proven": { "type": "boolean" } } } }, "difference": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, { "type": "null" } ] }, "balances_equal": { "type": [ "boolean", "null" ] }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "from_date", "to_date", "complete", "gaps", "incomplete_statement_count", "undated_statement_count", "partial_day_statement_count" ], "properties": { "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "complete": { "type": "boolean" }, "gaps": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "from_date", "to_date" ], "properties": { "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } } }, "incomplete_statement_count": { "type": "integer", "minimum": 0 }, "undated_statement_count": { "type": "integer", "minimum": 0 }, "partial_day_statement_count": { "type": "integer", "minimum": 0 } } }, "balance_issues": { "type": "array", "items": { "type": "string", "enum": [ "date_before_account_start", "closing_balance_currency_mismatch", "closing_balance_time_unproven", "statement_balance_conflict", "statement_balance_movement_mismatch", "closing_balance_missing", "closing_balance_conflict" ] } }, "entries": { "type": "object", "additionalProperties": false, "required": [ "count", "unprocessed_count", "partial_count", "needs_review_count", "source_review_count", "unknown_booking_date_count", "remaining_amount" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "unprocessed_count": { "type": "integer", "minimum": 0 }, "partial_count": { "type": "integer", "minimum": 0 }, "needs_review_count": { "type": "integer", "minimum": 0 }, "source_review_count": { "type": "integer", "minimum": 0 }, "unknown_booking_date_count": { "type": "integer", "minimum": 0 }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } } }, "reconciled": { "type": "boolean" } } } } }, "BankSalesSettlementInput": { "type": "object", "required": [ "document_public_id", "channel", "settlement_date", "amount" ], "additionalProperties": false, "properties": { "full_amount": { "type": "boolean", "description": "Explicit full receipt of the remaining document amount, without a payment-difference treatment. Same-currency amount must match outstanding. For a base-currency document with foreign receipt, omit receipt_fx: its base value is the outstanding document amount. Other foreign receipts retain their actual payment valuation." }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_currency_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "difference_treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ] }, "rc_contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Explicit RC counterparty, independent of the sales customer. Must be reachable through configured RC links in the authorized administrations. No name or email matching." }, "document_public_id": { "$ref": "#/components/schemas/Ulid" } }, "allOf": [ { "if": { "properties": { "channel": { "const": "rekening_courant" } }, "required": [ "channel" ] }, "then": { "required": [ "rc_contact_public_id" ], "properties": { "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "else": { "properties": { "rc_contact_public_id": { "type": "null" } } } } ] }, "BankSalesCustomerCreditRefundInput": { "type": "object", "required": [ "customer_credit_public_id", "channel", "settlement_date", "amount" ], "additionalProperties": false, "properties": { "customer_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "customer_credit_currency_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "rc_contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Explicit RC counterparty, independent of the sales customer. Must be reachable through configured RC links in the authorized administrations. No name or email matching." } }, "allOf": [ { "if": { "properties": { "channel": { "const": "rekening_courant" } }, "required": [ "channel" ] }, "then": { "required": [ "rc_contact_public_id" ], "properties": { "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "else": { "properties": { "rc_contact_public_id": { "type": "null" } } } } ] }, "BankSalesDocumentInput": { "type": "object", "required": [ "document_type", "invoice_date", "supply_date", "lines", "direct_settlement" ], "additionalProperties": false, "properties": { "document_type": { "type": "string", "const": "direct_sale" }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vat_context": { "oneOf": [ { "$ref": "#/components/schemas/SalesVatContextInput" }, { "type": "object", "maxProperties": 0 } ], "description": "Required for VAT-treated lines; omit for a receipt without consideration." }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesInput" }, { "type": "null" } ] }, "vies_proof": { "type": [ "string", "null" ], "maxLength": 4096 }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "$ref": "#/components/schemas/SalesDocumentLineInput" }, { "$ref": "#/components/schemas/SalesCreditLineInput" } ] } }, "direct_settlement": { "$ref": "#/components/schemas/SalesDirectSettlementInput" }, "original_document_public_ids": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" }, "description": "Internal credit sources, all in the same administration, customer and currency. Every credit line identifies one source." } }, "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "external_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/SalesCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "else": { "required": [ "currency_code" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/SalesDocumentLineInput" } } } } } ], "description": "Direct sale plus explicit receipt only. For treatments requiring VIES, supply an already obtained vies_proof; no remote verification is performed within bank processing. Does not issue a numbered invoice." }, "BankPurchasePaymentInput": { "type": "object", "additionalProperties": false, "properties": { "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Required only for current-account settlements: the explicitly selected existing contact of the own or a linked administration, independently of the supplier. The complete configured route and current write access to every involved administration are required." }, "payment_date": { "type": "string", "format": "date" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "document_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "difference_treatment": { "type": "string", "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_supplier_credit" ] }, "fx": { "$ref": "#/components/schemas/PurchasePaymentFxInput" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/PurchaseRouteEdgeAmountInput" } }, "allocations": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchasePayableAllocationInput" } }, "unallocated_payment": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/unallocated_payment" } }, "required": [ "supplier_public_id", "channel", "payment_date", "amount", "allocations" ], "allOf": [ { "oneOf": [ { "properties": { "unallocated_payment": { "const": true }, "allocations": { "maxItems": 0 }, "difference_treatment": { "const": "hold_supplier_credit" }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" } }, "required": [ "unallocated_payment", "supplier_public_id" ] }, { "properties": { "unallocated_payment": { "const": false }, "allocations": { "minItems": 1 } } } ] } ] }, "BankPurchaseRefundInput": { "type": "object", "additionalProperties": false, "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Required only for current-account settlements: the explicitly selected existing contact of the own or a linked administration, independently of the supplier. The complete configured route and current write access to every involved administration are required." }, "refund_date": { "type": "string", "format": "date" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "fx": { "$ref": "#/components/schemas/PurchasePaymentFxInput" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/PurchaseRouteEdgeAmountInput" } } }, "required": [ "supplier_credit_public_id", "channel", "refund_date", "amount" ] }, "BankPurchaseDocumentInput": { "type": "object", "additionalProperties": false, "properties": { "document_type": { "type": "string", "const": "purchase" }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "supplier_vat_identification_number": { "type": [ "string", "null" ], "maxLength": 32 }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "document_date": { "type": "string", "format": "date" }, "performance_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fx": { "$ref": "#/components/schemas/PurchaseFxEvidence" }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseCreateLineInput" } }, "payment": { "$ref": "#/components/schemas/PurchaseEmbeddedPaymentInput" }, "credit_allocations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseAllocationInput" } }, "acknowledged_duplicate_public_id": { "$ref": "#/components/schemas/Ulid" }, "acknowledged_duplicate_operation_index": { "type": "integer", "minimum": 0, "description": "Explicitly acknowledge a warned earlier purchase operation in this same ordered request. Mutually exclusive with acknowledged_duplicate_public_id; the earlier actual document identity is resolved only after persistence. Never invent a public ID." } }, "required": [ "document_type", "document_date", "performance_date", "currency_code", "lines", "payment" ] }, "BankProcessingOperation": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "sales_receipt" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankSalesSettlementInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "sales_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankSalesSettlementInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "sales_customer_credit_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankSalesCustomerCreditRefundInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "sales_document" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankSalesDocumentInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "purchase_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankPurchasePaymentInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "purchase_supplier_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankPurchaseRefundInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "purchase_payroll_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankPayrollRefundInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "purchase_document" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankPurchaseDocumentInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "manual_journal" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/PostJournalEntryRequest" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "bank_transfer" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankTransferInput" } } }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "loan" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankLoanInput" } }, "required": [ "type", "administration_public_id", "data" ] }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "vat_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "allOf": [ { "$ref": "#/components/schemas/VatReturnPaymentInput" }, { "properties": { "direction": { "const": "DBIT" } } } ] } }, "description": "Requires banking:write AND vat_returns:write. No purchases scope substitute. Source administration must equal the bank administration. Multiple operations share cumulative pending payment state." }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "type": "string", "const": "vat_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "allOf": [ { "$ref": "#/components/schemas/VatReturnPaymentInput" }, { "properties": { "direction": { "const": "CRDT" } } } ] } }, "description": "Requires banking:write AND vat_returns:write. No purchases scope substitute. Source administration must equal the bank administration. Multiple operations share cumulative pending payment state." }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "provider_payout" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "$ref": "#/components/schemas/BankProviderPayoutInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "owner_withdrawal" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "type": "object", "additionalProperties": false, "required": [ "kind", "posting_date", "bank_account_public_id", "private_ledger_account_public_id", "amount" ], "properties": { "kind": { "const": "withdrawal" }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No private bank account is registered." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." } } } }, "description": "IB only, same administration as the imported Bank entry. One typed capital source and one journal. No VAT, turnover, cost, contact, RC route or private bank account." }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "owner_contribution" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "type": "object", "additionalProperties": false, "required": [ "kind", "posting_date", "bank_account_public_id", "private_ledger_account_public_id", "amount" ], "properties": { "kind": { "const": "contribution" }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No private bank account is registered." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." } } } }, "description": "IB only, same administration as the imported Bank entry. One typed capital source and one journal. No VAT, turnover, cost, contact, RC route or private bank account." }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "tax_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "type": "object", "additionalProperties": false, "required": [ "kind", "posting_date", "bank_account_public_id", "tax_ledger_account_public_id", "amount" ], "properties": { "kind": { "const": "payment" }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191 } } } }, "description": "VPB only, same administration as the imported bank entry. One explicit suitable liability or receivable account. One typed source and journal, no new expense, VAT, invoice, contact or automatic assessment." }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "tax_refund" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "type": "object", "additionalProperties": false, "required": [ "kind", "posting_date", "bank_account_public_id", "tax_ledger_account_public_id", "amount" ], "properties": { "kind": { "const": "refund" }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191 } } } }, "description": "VPB only, same administration as the imported bank entry. One explicit suitable liability or receivable account. One typed source and journal, no new expense, VAT, invoice, contact or automatic assessment." }, { "type": "object", "additionalProperties": false, "required": [ "type", "administration_public_id", "data" ], "properties": { "type": { "const": "balance_liability_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "type": "object", "additionalProperties": false, "required": [ "kind", "posting_date", "bank_account_public_id", "balance_ledger_account_public_id", "amount" ], "properties": { "kind": { "const": "payment" }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191 } } } }, "description": "VPB only, same administration as the imported bank entry. One explicit suitable liability or receivable account. One typed source and journal, no new expense, VAT, invoice, contact or automatic assessment." }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "balance_dividend_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "allOf": [ { "$ref": "#/components/schemas/BankDividendPaymentInput" }, { "properties": { "kind": { "const": "dividend_payment" } } } ] } }, "required": [ "type", "administration_public_id", "data" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "balance_dividend_tax_payment" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "data": { "allOf": [ { "$ref": "#/components/schemas/BankDividendPaymentInput" }, { "properties": { "kind": { "const": "dividend_tax_payment" } } } ] } }, "required": [ "type", "administration_public_id", "data" ] } ] }, "BankProcessingPreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "links", "operations" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/BankLink" } }, "operations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/BankProcessingOperation" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankProcessingRequest": { "type": "object", "additionalProperties": false, "required": [ "links", "operations", "state_hash" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/BankLink" } }, "operations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/BankProcessingOperation" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankProcessingPreview": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "state_hash", "entry_public_id", "linked_amount", "remaining_amount", "warnings", "operations" ], "properties": { "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "dependent_changes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyExchangeJournal" }, { "$ref": "#/components/schemas/CurrencyExchangeDependentJournal" } ] } }, "entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "linked_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/BankLinkWarning" } }, "operations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "index", "type", "administration_public_id", "preview", "bank_legs" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "type": { "type": "string", "enum": [ "sales_receipt", "sales_refund", "sales_customer_credit_refund", "sales_document", "purchase_payment", "purchase_supplier_refund", "purchase_document", "manual_journal", "bank_transfer", "loan", "owner_withdrawal", "owner_contribution", "tax_payment", "tax_refund", "balance_liability_payment", "balance_dividend_payment", "balance_dividend_tax_payment", "purchase_payroll_refund" ] }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "preview": { "type": "object", "description": "The selected operation's existing Sales, Purchase, journal or own-transfer preview. No provisional public IDs are issued; purchase duplicate warnings may identify an earlier operation_index. Own transfers expose both real bank dates, participating bank accounts, clearing account/currency/movement, route edge_amounts and their journals with departure/arrival roles." }, "bank_legs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "direction", "amount", "currency_code", "dates" ], "properties": { "direction": { "$ref": "#/components/schemas/BankDirection" }, "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "currency_code": { "type": "string" }, "dates": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "InvoiceReminderSettings": { "type": "object", "additionalProperties": false, "required": [ "revision", "automatic", "days", "last_error_code" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "automatic": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 1000, "uniqueItems": true }, "last_error_code": { "type": [ "string", "null" ] } } }, "SaveInvoiceReminderSettingsRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "automatic", "days" ], "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "automatic": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 1000, "uniqueItems": true } }, "description": "All three fields are required. Automatic mode starts off. Enabling requires at least one explicitly selected day; no implicit schedule, sorting or deduplication. Days may be retained while automatic mode is off. Enabling binds the currently authorizing principal; edits while enabled do not replace it. Automatic recipients are the contact's current validated email address, rechecked before transport; absent or invalid addresses send nothing." }, "InvoiceReminderSettingsResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceReminderSettings" } } }, "InvoiceReminderSnapshot": { "type": "object", "additionalProperties": false, "required": [ "document_revision", "settings_revision", "reminder_revision", "state_hash" ], "properties": { "document_revision": { "type": "integer", "minimum": 1 }, "settings_revision": { "type": "integer", "minimum": 0 }, "reminder_revision": { "type": "integer", "minimum": 0 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "InvoiceReminderPreview": { "type": "object", "additionalProperties": false, "required": [ "document_public_id", "document_revision", "settings_revision", "reminder_revision", "state_hash", "current_outstanding", "currency_code", "due_date", "to_address", "day", "number" ], "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_revision": { "type": "integer", "minimum": 1 }, "settings_revision": { "type": "integer", "minimum": 0 }, "reminder_revision": { "type": "integer", "minimum": 0 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "current_outstanding": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{4}$", "description": "Exact current receivable in document currency, four storage decimals. No binary floating point." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "due_date": { "type": "string", "format": "date" }, "to_address": { "type": [ "string", "null" ], "format": "email" }, "day": { "type": "integer", "minimum": 1 }, "number": { "type": "string" } } }, "InvoiceReminderPreviewResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceReminderPreview" } } }, "InvoiceReminderLastDelivery": { "type": "object", "additionalProperties": false, "required": [ "public_id", "status", "created_at", "error_code", "retry_attempt", "retry_available_at", "retry_exhausted" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "failed", "uncertain" ] }, "created_at": { "type": "string", "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "retry_attempt": { "type": "integer", "minimum": 0, "maximum": 3 }, "retry_available_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest possible next attempt after a proven pre-transport temporary failure. Current eligibility, authority and settings are checked again; null is not a promise that a retry will run." }, "retry_exhausted": { "type": "boolean" } }, "description": "Automatic reminders preserve every attempt. Only dns_unavailable and deadline_expired failures before transport may retry up to three times, waiting 15 minutes, 1 hour and 24 hours from the previous completion. Historical endpoint_unavailable and uncertain sends never retry automatically." }, "InvoiceReminderReadyItem": { "type": "object", "additionalProperties": false, "required": [ "document_public_id", "number", "contact", "due_date", "current_outstanding", "currency_code", "day", "reminder_preview", "last_delivery", "automatic_error_code" ], "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "contact": { "type": "object", "additionalProperties": false, "required": [ "display_name", "email" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" } } }, "due_date": { "type": "string", "format": "date" }, "current_outstanding": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{4}$", "description": "Exact current receivable in document currency, four storage decimals. No binary floating point." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "day": { "type": "integer", "minimum": 1 }, "reminder_preview": { "$ref": "#/components/schemas/InvoiceReminderSnapshot" }, "last_delivery": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceReminderLastDelivery" }, { "type": "null" } ] }, "automatic_error_code": { "type": [ "string", "null" ], "description": "Safe current automatic-reminder failure code, or null. Only present as a non-null value while automatic reminders are enabled." } } }, "InvoiceReminderCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceReminderReadyItem" } }, "links": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } } } }, "RequestInvoiceReminder": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "expected_settings_revision", "expected_reminder_revision", "state_hash", "to_address" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "expected_settings_revision": { "type": "integer", "minimum": 1 }, "expected_reminder_revision": { "type": "integer", "minimum": 0 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "to_address": { "type": "string", "format": "email", "maxLength": 254 } } }, "SaveInvoiceRecurrenceRequest": { "type": "object", "additionalProperties": false, "required": [ "public_id", "expected_revision", "frequency", "start_date" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 0 }, "source_draft_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Required for a new series. Explicitly replace the saved template on edit; omitting both source fields retains it." }, "source_draft_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "frequency": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, "start_date": { "type": "string", "format": "date" }, "payment_term_days": { "type": "integer", "minimum": 0, "maximum": 65535, "default": 14 }, "automatic_finalize": { "type": "boolean", "default": false }, "automatic_send": { "type": "boolean", "default": false }, "to_address": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 } }, "description": "Copy a saved, unissued invoice draft from this administration, at its exact revision. Save replaces the complete schedule settings, including on update: omitted payment_term_days, automatic_finalize, automatic_send and to_address become 14, false, false and null. Only omission of both source fields retains the current template. Source drafts with direct_settlement are rejected without mutation. The copy repeats invoices only; receipts remain separate. Automatic sending requires automatic_finalize, explicit recipient, own SMTP and current invoices:send authority. Non-null to_address is prohibited without automatic_send. Current actor and stored principal are rechecked; editing never replaces the original principal. Future schedule/financial inputs retain the existing Sales and VAT contracts." }, "InvoiceRecurrence": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "status", "source_draft_public_id", "source_draft_revision", "frequency", "start_date", "next_run_on", "payment_term_days", "automatic_finalize", "automatic_send", "to_address", "last_error_code", "last_error_fields", "created_at", "updated_at" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active", "paused", "ended" ] }, "source_draft_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_draft_revision": { "type": "integer", "minimum": 1 }, "frequency": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, "start_date": { "type": "string", "format": "date" }, "next_run_on": { "type": "string", "format": "date" }, "payment_term_days": { "type": "integer", "minimum": 0, "maximum": 65535 }, "automatic_finalize": { "type": "boolean" }, "automatic_send": { "type": "boolean" }, "to_address": { "type": [ "string", "null" ] }, "last_error_code": { "type": [ "string", "null" ] }, "last_error_fields": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceRecurrenceResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceRecurrence" } } }, "InvoiceRecurrenceCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceRecurrence" } }, "links": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } } } }, "InvoiceRecurrenceOccurrence": { "type": "object", "additionalProperties": false, "required": [ "public_id", "scheduled_on", "series_revision", "draft_public_id", "draft_revision", "sales_document_public_id", "delivery_public_id", "status", "error_code", "error_fields", "created_at", "updated_at" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "scheduled_on": { "type": "string", "format": "date" }, "series_revision": { "type": "integer", "minimum": 1 }, "draft_public_id": { "$ref": "#/components/schemas/Ulid" }, "draft_revision": { "type": "integer", "minimum": 1 }, "sales_document_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "delivery_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "draft", "finalized", "queued", "blocked", "skipped" ] }, "error_code": { "type": [ "string", "null" ] }, "error_fields": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceRecurrenceOccurrenceCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceRecurrenceOccurrence" } }, "links": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } } } }, "InvoiceRecurrenceTransitionRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } }, "QuotePreviewLineInput": { "type": "object", "required": [ "vat_treatment_code", "amount_mode", "quantity", "unit_price" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Optional own-administration reference; ignored by the fiscal preview and no account or mapping is required." }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "quantity": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "unit_price": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } } }, "QuotePreviewInput": { "type": "object", "required": [ "document_type", "contact_public_id", "invoice_date", "supply_date", "currency_code", "vat_context", "lines" ], "additionalProperties": false, "properties": { "document_type": { "type": "string", "const": "issued_invoice" }, "contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vat_context": { "$ref": "#/components/schemas/SalesVatContextInput" }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesInput" }, { "type": "null" } ] }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/QuotePreviewLineInput" } } }, "description": "Unsaved quotation fiscal projection. Requires the existing quotation output completeness (named issuer/customer and described priced lines), but no revenue account, mappings, open fiscal year or ordinary document FX. No settlement, credit, issued number, saved draft identity, state hash or VIES proof input is accepted. EU-B2C uses the recorded inclusive destination-VAT start day, voluntary election and route facts; quotation projection does not calculate turnover or require prospective threshold FX." }, "QuotePreviewAmounts": { "type": "object", "additionalProperties": false, "required": [ "native_net_amount", "native_vat_amount", "native_gross_amount" ], "properties": { "native_net_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact amount in document currency, formatted at its minor-unit precision." }, "native_vat_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact amount in document currency, formatted at its minor-unit precision." }, "native_gross_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact amount in document currency, formatted at its minor-unit precision." } } }, "QuotePreviewResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "kind", "currency_code", "lines", "totals", "vies_proof", "warnings" ], "properties": { "kind": { "type": "string", "const": "quote" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/QuotePreviewAmounts" } }, "totals": { "$ref": "#/components/schemas/QuotePreviewAmounts" }, "vies_proof": { "type": [ "string", "null" ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewNotice" } } } } } }, "IssuedInvoiceLineInput": { "type": "object", "required": [ "revenue_ledger_account_public_id", "vat_treatment_code", "amount_mode", "quantity", "unit_price" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "quantity": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "unit_price": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } } }, "IssuedCreditLineInput": { "type": "object", "required": [ "quantity", "unit_price" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "quantity": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "unit_price": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "original_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } }, "anyOf": [ { "required": [ "original_line_public_id" ], "properties": { "original_line_public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "required": [ "original_line_number" ], "properties": { "original_line_number": { "type": "integer", "minimum": 1, "maximum": 100 } } } ] }, "IssuedInvoicePreviewInput": { "type": "object", "required": [ "document_type", "invoice_date", "supply_date", "lines" ], "additionalProperties": false, "properties": { "document_type": { "type": "string", "enum": [ "issued_invoice", "issued_credit_note" ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ], "maxLength": 0, "description": "Omit or leave empty. The issued number is assigned only when a draft is finalized." }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vat_context": { "$ref": "#/components/schemas/SalesVatContextInput" }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesInput" }, { "type": "null" } ] }, "vies_proof": { "type": [ "string", "null" ], "maxLength": 4096 }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "$ref": "#/components/schemas/IssuedInvoiceLineInput" }, { "$ref": "#/components/schemas/IssuedCreditLineInput" } ] } }, "direct_settlement": { "oneOf": [ { "$ref": "#/components/schemas/SalesDirectSettlementInput" }, { "type": "null" } ] }, "original_document_public_ids": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" }, "description": "Internal credit sources, all in the same administration, customer and currency. Every credit line identifies one source." } }, "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "issued_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/IssuedCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "else": { "required": [ "currency_code", "vat_context", "contact_public_id" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/IssuedInvoiceLineInput" } } } } } ], "description": "Issuance preview only, never direct creation via sales/documents. The saved draft is finalized separately. Quantity times unit_price is rounded half-up to the currency minor unit before the existing VAT calculation. Optional amount must equal that result. Internal credits inherit the original account, currency and tax facts." }, "InvoiceDraftDocument": { "type": "object", "additionalProperties": false, "properties": { "document_type": { "type": [ "string", "null" ], "enum": [ "issued_invoice", "issued_credit_note", null ] }, "original_document_public_id": { "anyOf": [ { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, { "type": [ "null" ] } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact_public_id": { "anyOf": [ { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, { "type": [ "null" ] } ] }, "external_number": { "type": "null" }, "invoice_date": { "type": [ "string", "null" ], "format": "date" }, "supply_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "vat_context": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "region": { "type": [ "string", "null" ], "enum": [ "nl", "eu", "non_eu", null ] }, "supply_type": { "type": [ "string", "null" ], "enum": [ "goods", "services", "digital_services", null ] }, "customer_type": { "type": [ "string", "null" ], "enum": [ "b2b", "b2c", null ] } } }, "fx": { "anyOf": [ { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": [ "string", "null" ], "enum": [ "rate", "converted_amount", null ] }, "rate": { "type": [ "string", "null" ], "maxLength": 40 }, "converted_base_amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } } }, { "type": [ "null" ] } ] }, "vies": { "anyOf": [ { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "source": { "type": [ "string", "null" ], "enum": [ "official", "manual_evidence", null ] }, "evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 } } }, { "type": [ "null" ] } ] }, "lines": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, "vat_treatment_code": { "type": [ "string", "null" ], "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ] }, "amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": [ "string", "null" ], "enum": [ "inclusive", "exclusive", null ] }, "margin_method": { "type": [ "string", "null" ], "enum": [ "none", "individual", "globalisation", null ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "quantity": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "unit_price": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } } } }, "direct_settlement": { "anyOf": [ { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "full_amount": { "type": [ "boolean", "null" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "bank", "cash", "rekening_courant", "linked_administration", null ] }, "receiving_administration_public_id": { "anyOf": [ { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, { "type": [ "null" ] } ] }, "ledger_account_public_id": { "anyOf": [ { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, { "type": [ "null" ] } ] }, "settlement_date": { "type": [ "string", "null" ], "format": "date", "examples": [ "2026-08-25" ] }, "amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$", "examples": [ "274.00" ] }, "document_currency_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$", "examples": [ "274.00" ] }, "receipt_fx": { "anyOf": [ { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": [ "string", "null" ], "enum": [ "rate", "converted_amount", null ] }, "rate": { "type": [ "string", "null" ], "maxLength": 40 }, "converted_base_amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } } }, { "type": [ "null" ] } ] }, "route_configuration_public_ids": { "type": [ "array", "null" ], "maxItems": 8, "uniqueItems": true, "items": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] } }, "edge_amounts": { "type": [ "array", "null" ], "maxItems": 8, "items": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "configuration_public_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, "native_amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_amounts": { "type": [ "array", "null" ], "maxItems": 8, "items": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "administration_public_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, "base_amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } } } } } } }, "difference_treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ], "examples": [ "leave_open" ] }, "document_fx": { "anyOf": [ { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": [ "string", "null" ], "enum": [ "rate", "converted_amount", null ] }, "rate": { "type": [ "string", "null" ], "maxLength": 40 }, "converted_base_amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } } }, { "type": [ "null" ] } ] }, "rc_contact_public_id": { "anyOf": [ { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, { "type": [ "null" ] } ] } } }, { "type": [ "null" ] } ] }, "original_document_public_ids": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" }, "description": "Internal credit sources, all in the same administration, customer and currency. Every credit line identifies one source." } }, "description": "Closed incomplete concept input: supplied fields retain their types, but financial completeness is checked only at preview/finalization. kind determines document_type; quote/invoice use issued_invoice, credit_note uses issued_credit_note. Null lines are rejected; an empty lines array is permitted. No issued number or VIES proof can be stored." }, "InvoicePresentation": { "type": "object", "additionalProperties": false, "properties": { "locale": { "type": "string", "enum": [ "nl", "en" ] }, "note": { "type": [ "string", "null" ], "maxLength": 5000 } }, "description": "Document language and note only. Current logo, font, accent and payment instructions belong exclusively to administration invoice-branding. Former style keys are rejected." }, "InvoicePresentationProjection": { "type": "object", "additionalProperties": false, "properties": { "locale": { "type": "string", "enum": [ "nl", "en" ] }, "note": { "type": [ "string", "null" ], "maxLength": 5000 } }, "description": "Document language and note only. Current logo, font, accent and payment instructions belong exclusively to administration invoice-branding. Former style keys are rejected.", "required": [ "locale", "note" ] }, "InvoiceDraftSummary": { "type": "object", "additionalProperties": false, "required": [ "public_id", "kind", "revision", "accepted_at", "source_quote_public_id", "sales_document_public_id", "document", "presentation", "created_at", "updated_at", "restricted_fields", "quote_locked" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "kind": { "type": "string", "enum": [ "invoice", "credit_note", "quote" ] }, "revision": { "type": "integer", "minimum": 1 }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_quote_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "sales_document_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceDraftDocument" }, { "type": "null" } ] }, "presentation": { "anyOf": [ { "$ref": "#/components/schemas/InvoicePresentationProjection" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "restricted_fields": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "document.direct_settlement" ] } }, "quote_locked": { "type": "boolean", "description": "True only for a quotation with an existing derived draft or finalized invoice. Content and acceptance cannot change; existing no-op replay remains available." } }, "description": "Tenant-safe draft collection. Presentation contains only language and note. Finalized drafts expose document/presentation null." }, "UpdateInvoicePresentationRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "presentation" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "presentation": { "$ref": "#/components/schemas/InvoicePresentation" } }, "description": "Replace current document language and note with optimistic concurrency. Financial and branding fields are rejected. Existing fiscal-year edit boundaries apply." }, "InvoiceBranding": { "type": "object", "additionalProperties": false, "required": [ "revision", "font", "accent", "logo_data_uri", "account_number", "account_holder" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "font": { "type": "string", "enum": [ "sans", "serif", "mono" ] }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "logo_data_uri": { "type": [ "string", "null" ], "maxLength": 2666691, "description": "Strict local PNG/JPEG data URI; at most 2 MB and 4 million pixels. Omission preserves; null removes. No archive." }, "account_number": { "type": [ "string", "null" ], "maxLength": 100, "description": "Explicit bank account number or IBAN, no bank selection or normalization. Omission preserves; null removes." }, "account_holder": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional explicit account holder; no inferred fallback. Omission preserves; null removes." } } }, "UpdateInvoiceBrandingRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "font", "accent" ], "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "font": { "type": "string", "enum": [ "sans", "serif", "mono" ] }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "logo_data_uri": { "type": [ "string", "null" ], "maxLength": 2666691, "description": "Strict local PNG/JPEG data URI; at most 2 MB and 4 million pixels. Omission preserves; null removes. No archive." }, "account_number": { "type": [ "string", "null" ], "maxLength": 100, "description": "Explicit bank account number or IBAN, no bank selection or normalization. Omission preserves; null removes." }, "account_holder": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional explicit account holder; no inferred fallback. Omission preserves; null removes." } } }, "InvoicePresentationResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "presentation" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "presentation": { "$ref": "#/components/schemas/InvoicePresentation" } } } } }, "SaveInvoiceDraftRequest": { "type": "object", "additionalProperties": false, "required": [ "public_id", "expected_revision", "kind", "document" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 0 }, "kind": { "type": "string", "enum": [ "invoice", "credit_note", "quote" ] }, "document": { "$ref": "#/components/schemas/InvoiceDraftDocument" }, "presentation": { "$ref": "#/components/schemas/InvoicePresentation" }, "source_quote_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "source_quote_revision": { "type": [ "integer", "null" ], "minimum": 1, "description": "Required when first saving an invoice derived from a quotation; echo the invoice-prefill source_quote_revision. A stale or missing token returns invoice_quote_source_changed. Not version history." } }, "description": "Supply a client-generated ULID and revision 0 for a new draft. Reuse the identity/revision for retries. Identical content can be replayed at the current or immediately preceding revision; stale changed input conflicts. This is nonfinancial revision-based storage, not permanent command replay. source_quote_public_id is valid only for invoice and cannot later change. A quotation with any derived invoice draft is read-only. Deleting all unissued derivatives unlocks it; an issued derivative keeps it locked even after financial deletion. Identical no-op quotation saves remain idempotent." }, "InvoiceDraft": { "type": "object", "additionalProperties": false, "required": [ "public_id", "kind", "revision", "accepted_at", "source_quote_public_id", "sales_document_public_id", "document", "presentation", "created_at", "updated_at", "restricted_fields", "quote_locked" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "kind": { "type": "string", "enum": [ "invoice", "credit_note", "quote" ] }, "revision": { "type": "integer", "minimum": 1 }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_quote_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "sales_document_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceDraftDocument" }, { "type": "null" } ] }, "presentation": { "anyOf": [ { "$ref": "#/components/schemas/InvoicePresentation" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "restricted_fields": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "document.direct_settlement" ] } }, "quote_locked": { "type": "boolean", "description": "True only for a quotation with an existing derived draft or finalized invoice. Content and acceptance cannot change; existing no-op replay remains available." } }, "description": "Only public identifiers. Finalized drafts expose their Sales pointer with document/presentation null. Out-of-scope linked-administration route metadata is omitted." }, "InvoiceDraftResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceDraft" } } }, "InvoiceDraftCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDraftSummary" } }, "links": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } } } }, "InvoiceRevisionRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } }, "FinalizeInvoiceRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "state_hash" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "vies_proof": { "type": [ "string", "null" ], "maxLength": 4096 } } }, "QuoteInvoicePrefillResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "kind", "source_quote_public_id", "source_quote_revision", "document", "presentation", "restricted_fields" ], "properties": { "kind": { "type": "string", "const": "invoice" }, "source_quote_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_quote_revision": { "type": "integer", "minimum": 1 }, "document": { "$ref": "#/components/schemas/InvoiceDraftDocument" }, "presentation": { "$ref": "#/components/schemas/InvoicePresentation" }, "restricted_fields": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "document.direct_settlement" ] } } } } } }, "InvoiceRecipient": { "type": "object", "additionalProperties": false, "required": [ "name", "street", "house_number", "house_number_addition", "postal_code", "city", "country_code", "vat_id" ], "properties": { "name": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "house_number_addition": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] } } }, "InvoiceIssuer": { "type": "object", "additionalProperties": false, "required": [ "name", "street", "house_number", "house_number_addition", "postal_code", "city", "country_code", "vat_id", "kvk_number" ], "properties": { "name": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "house_number_addition": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] }, "kvk_number": { "type": [ "string", "null" ] } } }, "InvoiceDetails": { "type": "object", "additionalProperties": false, "required": [ "issuer", "recipient", "presentation" ], "properties": { "issuer": { "$ref": "#/components/schemas/InvoiceIssuer" }, "recipient": { "$ref": "#/components/schemas/InvoiceRecipient" }, "presentation": { "$ref": "#/components/schemas/InvoicePresentationProjection" } } }, "InvoiceDeliveryRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "expected_settings_revision", "to_address" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "expected_settings_revision": { "type": "integer", "minimum": 1 }, "to_address": { "type": "string", "format": "email", "maxLength": 254 }, "include_payment_link": { "type": "boolean", "description": "Optional, false when omitted. Only issued invoices with enabled Mollie settings support true; quotations and credit notes do not. No remote payment is created while requesting email delivery." } } }, "InvoiceDeliveryResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "public_id", "status", "replayed", "error_code", "accepted_at" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "failed", "uncertain" ] }, "replayed": { "type": "boolean" }, "error_code": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "Ulid": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "01J00000000000000000000000" ] }, "MeResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "user", "token", "administration_public_ids" ], "additionalProperties": false, "properties": { "user": { "$ref": "#/components/schemas/User" }, "token": { "$ref": "#/components/schemas/TokenMetadata" }, "administration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" } } } } } }, "User": { "type": "object", "required": [ "public_id", "display_name", "locale" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "display_name": { "type": "string" }, "locale": { "type": "string", "enum": [ "nl", "en" ] } } }, "TokenMetadata": { "type": "object", "required": [ "public_id", "name", "abilities", "expires_at" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "maxLength": 100 }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "administrations:read", "fiscal_years:read", "fiscal_years:write", "ledger_accounts:read", "ledger_accounts:write", "journal_entries:read", "journal_entries:write", "general_ledger:read", "financial_reports:read", "opening_balances:read", "opening_balances:write", "vat_treatments:read", "fx_revaluations:read", "fx_revaluations:write", "contacts:read", "contacts:write", "administration_relations:read", "administration_relations:write", "rekening_courant:read", "rekening_courant:write", "sales:read", "sales:write", "invoices:send", "purchases:read", "purchases:write", "banking:read", "banking:write", "fixed_assets:read", "fixed_assets:write", "investments:read", "investments:write", "loans:read", "loans:write" ] } }, "expires_at": { "type": "string", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] } } }, "Administration": { "type": "object", "required": [ "public_id", "company_name", "legal_form", "tax_regime", "country_code", "currency_code", "timezone", "status", "access_role" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "company_name": { "type": "string" }, "legal_form": { "type": "string", "enum": [ "sole_proprietorship", "general_partnership", "professional_partnership", "limited_partnership", "private_limited_company", "public_limited_company", "cooperative", "foundation", "association" ] }, "tax_regime": { "type": [ "string", "null" ], "enum": [ "income_tax", "corporate_tax", "none", null ], "description": "Explicit administration tax-return context. Null means not configured, distinct from the explicit choice none. This setting does not itself recalculate journals or historical asset schedules." }, "country_code": { "type": "string", "const": "NL" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "timezone": { "type": "string", "examples": [ "Europe/Amsterdam" ] }, "status": { "type": "string", "enum": [ "active", "suspended", "archived" ] }, "access_role": { "type": "string", "enum": [ "owner", "manager", "viewer" ] } } }, "AdministrationCollection": { "type": "object", "required": [ "data", "links", "meta" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Administration" } }, "links": { "type": "object", "required": [ "next" ], "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ], "format": "uri" } } }, "meta": { "type": "object", "required": [ "per_page" ], "additionalProperties": false, "properties": { "per_page": { "type": "integer", "minimum": 1, "maximum": 100 } } } } }, "ContactSummary": { "type": "object", "required": [ "public_id", "contact_number", "display_name", "status", "contact_type", "legal_form", "company_name", "first_name", "middle_name", "last_name", "email", "kvk_number", "vat_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "contact_number": { "type": "integer", "minimum": 1 }, "display_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "contact_type": { "type": "string", "enum": [ "person", "organization" ], "description": "Use organization for a sole proprietorship; person is a private individual without a legal form." }, "legal_form": { "type": [ "string", "null" ], "description": "Optional for organization, including sole_proprietorship. Must be null for person." }, "company_name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "middle_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "kvk_number": { "type": [ "string", "null" ], "pattern": "^[0-9]{8}$" }, "vat_id": { "type": [ "string", "null" ] } }, "description": "Contact types are commercial categories: person is a private individual with no legal form; every business, including a sole proprietorship, uses organization. Organization requires company_name. Proprietor name, gender, birth_date and BSN are optional only for sole_proprietorship; other organizations cannot retain personal fields. Sole proprietorships cannot have an RSIN. PATCH omits unchanged fields; blank BSN preserves a stored BSN." }, "MaskedBsn": { "type": "object", "required": [ "present", "masked" ], "additionalProperties": false, "properties": { "present": { "type": "boolean" }, "masked": { "type": [ "string", "null" ], "description": "At most the final two digits are visible." } } }, "Contact": { "allOf": [ { "$ref": "#/components/schemas/ContactSummary" }, { "type": "object", "required": [ "initials", "street", "house_number", "house_number_addition", "postal_code", "city", "country_code", "gender", "birth_date", "phone", "bsn", "rsin", "ob_number", "established_on", "notes", "created_at", "updated_at" ], "properties": { "initials": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "house_number_addition": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$" }, "gender": { "type": [ "string", "null" ], "enum": [ "unknown", "male", "female", null ] }, "birth_date": { "type": [ "string", "null" ], "format": "date" }, "phone": { "type": [ "string", "null" ] }, "bsn": { "$ref": "#/components/schemas/MaskedBsn" }, "rsin": { "type": [ "string", "null" ] }, "ob_number": { "type": [ "string", "null" ] }, "established_on": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } } ], "unevaluatedProperties": false }, "ContactResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "ContactCollection": { "type": "object", "required": [ "data", "links" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactSummary" } }, "links": { "type": "object", "required": [ "previous", "next" ], "additionalProperties": false, "properties": { "previous": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } } } } }, "ContactStatisticsResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "summary", "legal_forms", "genders", "countries" ], "additionalProperties": false, "properties": { "summary": { "type": "object", "required": [ "total", "active", "inactive", "persons", "organizations", "sole_proprietorships" ], "additionalProperties": false, "properties": { "total": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "inactive": { "type": "integer", "minimum": 0 }, "persons": { "type": "integer", "minimum": 0 }, "organizations": { "type": "integer", "minimum": 0 }, "sole_proprietorships": { "type": "integer", "minimum": 0 } } }, "legal_forms": { "type": "array", "items": { "$ref": "#/components/schemas/ContactStatisticBucket" } }, "genders": { "type": "array", "items": { "$ref": "#/components/schemas/ContactStatisticBucket" } }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/ContactStatisticBucket" } } } } } }, "ContactStatisticBucket": { "type": "object", "required": [ "code", "label", "count" ], "additionalProperties": false, "properties": { "code": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } } }, "ContactInput": { "type": "object", "properties": { "contact_number": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "contact_type": { "type": "string", "enum": [ "person", "organization" ], "description": "Use organization for a sole proprietorship; person is a private individual without a legal form." }, "legal_form": { "type": [ "string", "null" ], "description": "Optional for organization, including sole_proprietorship. Must be null for person." }, "company_name": { "type": [ "string", "null" ], "maxLength": 255 }, "initials": { "type": [ "string", "null" ], "maxLength": 30 }, "first_name": { "type": [ "string", "null" ], "maxLength": 100 }, "middle_name": { "type": [ "string", "null" ], "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "maxLength": 100 }, "street": { "type": [ "string", "null" ], "maxLength": 255 }, "house_number": { "type": [ "string", "null" ], "maxLength": 30 }, "house_number_addition": { "type": [ "string", "null" ], "maxLength": 30 }, "postal_code": { "type": [ "string", "null" ], "maxLength": 20 }, "city": { "type": [ "string", "null" ], "maxLength": 100 }, "country_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$" }, "gender": { "type": [ "string", "null" ], "enum": [ "unknown", "male", "female", null ] }, "birth_date": { "type": [ "string", "null" ], "format": "date" }, "phone": { "type": [ "string", "null" ], "maxLength": 30 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "bsn": { "type": [ "string", "null" ], "writeOnly": true }, "remove_bsn": { "type": "boolean", "writeOnly": true, "description": "Explicitly delete the stored BSN. An omitted or blank BSN preserves it for a private individual or sole proprietorship." }, "kvk_number": { "type": [ "string", "null" ] }, "rsin": { "type": [ "string", "null" ] }, "ob_number": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ], "maxLength": 32 }, "established_on": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] }, "remove_personal_details": { "type": "boolean", "writeOnly": true, "description": "Explicit consent to remove stored name fields, gender, birth_date and any BSN when changing to an organization without legal form sole_proprietorship. Required if that change would remove stored personal details; omission preserves the contact and returns a validation error. This flag is never persisted." } }, "description": "Contact types are commercial categories: person is a private individual with no legal form; every business, including a sole proprietorship, uses organization. Organization requires company_name. Proprietor name, gender, birth_date and BSN are optional only for sole_proprietorship; other organizations cannot retain personal fields. Sole proprietorships cannot have an RSIN. PATCH omits unchanged fields; blank BSN preserves a stored BSN." }, "CreateContactRequest": { "allOf": [ { "$ref": "#/components/schemas/ContactInput" }, { "type": "object", "required": [ "status", "contact_type" ] } ], "unevaluatedProperties": false }, "UpdateContactRequest": { "allOf": [ { "$ref": "#/components/schemas/ContactInput" } ], "minProperties": 1, "unevaluatedProperties": false, "description": "Partial update: omitted fields remain unchanged. Explicit contact-type or legal-form changes retain the existing type-specific field rules. A person with a stored BSN can become an organization only with explicit remove_bsn=true." }, "ContactRelationship": { "type": "object", "required": [ "public_id", "relationship_type", "forward_label", "inverse_label", "source", "target" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "relationship_type": { "type": "string", "enum": [ "director_of", "shareholder_of", "owner_of", "partner_of", "parent_of", "contact_person_of", "employed_by", "part_of", "affiliated_with" ] }, "forward_label": { "type": "string" }, "inverse_label": { "type": "string" }, "source": { "$ref": "#/components/schemas/ContactIdentity" }, "target": { "$ref": "#/components/schemas/ContactIdentity" } } }, "ContactIdentity": { "type": "object", "required": [ "public_id", "display_name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "display_name": { "type": "string" } } }, "CreateContactRelationshipRequest": { "type": "object", "required": [ "source_contact_public_id", "target_contact_public_id", "relationship_type" ], "additionalProperties": false, "properties": { "source_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "target_contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "relationship_type": { "type": "string", "enum": [ "director_of", "shareholder_of", "owner_of", "partner_of", "parent_of", "contact_person_of", "employed_by", "part_of", "affiliated_with" ] }, "direction": { "type": "string", "enum": [ "forward", "inverse" ], "default": "forward" } } }, "ContactRelationshipResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContactRelationship" } } }, "ContactRelationshipCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactRelationship" } } } }, "ContactRelationRequest": { "type": "object", "required": [ "contact_public_id" ], "additionalProperties": false, "properties": { "contact_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "AdministrationLinkRequest": { "type": "object", "required": [ "target_administration_public_id" ], "additionalProperties": false, "properties": { "target_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "description": "A supported currency. Required for a new link with different accounting currencies; omit for equal currencies, which use their common currency. No exchange rate." } } }, "ContactAdministrationLinkRequest": { "type": "object", "required": [ "contact_public_id", "target_administration_public_id" ], "additionalProperties": false, "properties": { "contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "target_administration_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "RelationMutationResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "public_id", "status", "revision" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "enum": [ "active", "inactive", "draft", "ready" ] }, "revision": { "type": "integer", "minimum": 1 } } } } }, "RelationContactIdentity": { "type": "object", "required": [ "public_id", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "person", "organization" ] } } }, "ShareholderRelation": { "type": "object", "required": [ "public_id", "contact", "status", "revision", "configuration_public_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "contact": { "$ref": "#/components/schemas/RelationContactIdentity" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "revision": { "type": "integer", "minimum": 1 }, "configuration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } } }, "ContactAdministrationRelation": { "type": "object", "required": [ "public_id", "contact", "target_administration", "restricted_target", "status", "revision" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "contact": { "$ref": "#/components/schemas/RelationContactIdentity" }, "target_administration": { "oneOf": [ { "$ref": "#/components/schemas/RelationContactIdentity" }, { "type": "null" } ] }, "restricted_target": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "revision": { "type": "integer", "minimum": 1 } } }, "AdministrationRelation": { "type": "object", "required": [ "public_id", "counterpart", "restricted_counterpart", "status", "revision", "configuration_public_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "counterpart": { "oneOf": [ { "$ref": "#/components/schemas/RelationContactIdentity" }, { "type": "null" } ] }, "restricted_counterpart": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "revision": { "type": "integer", "minimum": 1 }, "configuration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } } }, "AdministrationRelationsResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "shareholders", "contact_administration_links", "administration_links" ], "additionalProperties": false, "properties": { "shareholders": { "type": "array", "items": { "$ref": "#/components/schemas/ShareholderRelation" } }, "contact_administration_links": { "type": "array", "items": { "$ref": "#/components/schemas/ContactAdministrationRelation" } }, "administration_links": { "type": "array", "items": { "$ref": "#/components/schemas/AdministrationRelation" } } } } } }, "CurrentAccountPositionConfigurationInput": { "type": "object", "required": [ "administration_public_id", "receivable_account_public_id", "payable_account_public_id" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "receivable_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payable_account_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "PutCurrentAccountConfigurationRequest": { "type": "object", "required": [ "counterparty_type", "counterparty_public_id", "denomination_currency_code", "positions" ], "additionalProperties": false, "properties": { "counterparty_type": { "type": "string", "enum": [ "contact", "administration" ], "description": "Financial identity; independent of shareholder, director, partner or owner roles." }, "counterparty_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "positions": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "$ref": "#/components/schemas/CurrentAccountPositionConfigurationInput" } } } }, "CurrentAccountBaseAmountInput": { "type": "object", "required": [ "administration_public_id", "base_amount" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "base_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } } }, "CurrentAccountEdgeAmountInput": { "type": "object", "required": [ "configuration_public_id", "native_amount" ], "additionalProperties": false, "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountBaseAmountInput" } } } }, "CurrentAccountTransactionInput": { "type": "object", "required": [ "target_type", "target_public_id", "settlement_ledger_account_public_id", "posting_date", "description", "direction", "native_amount" ], "additionalProperties": false, "properties": { "target_type": { "type": "string", "const": "contact", "description": "Concrete Contact counterparty; its shareholder, director, partner, member or owner role is not part of the financial identity." }, "target_public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Active base-currency bank, cash or savings account." }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountEdgeAmountInput" } }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." }, "settlement_native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,12})?$", "description": "Required, positive actual native bank amount for fixed_foreign settlement accounts; forbidden for base_only. RC denomination and edge equivalents retain their existing meaning." } } }, "PostCurrentAccountTransactionRequest": { "type": "object", "required": [ "target_type", "target_public_id", "settlement_ledger_account_public_id", "posting_date", "description", "direction", "native_amount", "state_hash" ], "additionalProperties": false, "properties": { "target_type": { "type": "string", "const": "contact" }, "target_public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountEdgeAmountInput" } }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." }, "settlement_native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,12})?$", "description": "Required, positive actual native bank amount for fixed_foreign settlement accounts; forbidden for base_only. RC denomination and edge equivalents retain their existing meaning." } } }, "PreviewUpdateCurrentAccountTransactionRequest": { "type": "object", "required": [ "target_type", "target_public_id", "settlement_ledger_account_public_id", "posting_date", "description", "direction", "native_amount", "expected_revision" ], "additionalProperties": false, "properties": { "target_type": { "type": "string", "const": "contact" }, "target_public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountEdgeAmountInput" } }, "expected_revision": { "type": "integer", "minimum": 1 }, "settlement_native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,12})?$", "description": "Required, positive actual native bank amount for fixed_foreign settlement accounts; forbidden for base_only. RC denomination and edge equivalents retain their existing meaning." } } }, "UpdateCurrentAccountTransactionRequest": { "type": "object", "required": [ "target_type", "target_public_id", "settlement_ledger_account_public_id", "posting_date", "description", "direction", "native_amount", "state_hash", "expected_revision" ], "additionalProperties": false, "properties": { "target_type": { "type": "string", "const": "contact" }, "target_public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountEdgeAmountInput" } }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 }, "settlement_native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,12})?$", "description": "Required, positive actual native bank amount for fixed_foreign settlement accounts; forbidden for base_only. RC denomination and edge equivalents retain their existing meaning." } } }, "DeleteCurrentAccountTransactionRequest": { "type": "object", "required": [ "expected_revision" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Required under the periodic currency method; use the complete deletion preview." } } }, "CurrentAccountLedgerIdentity": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "CurrentAccountPositionConfiguration": { "type": "object", "required": [ "public_id", "accounts" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "accounts": { "type": "object", "required": [ "receivable", "payable" ], "additionalProperties": false, "properties": { "receivable": { "$ref": "#/components/schemas/CurrentAccountLedgerIdentity" }, "payable": { "$ref": "#/components/schemas/CurrentAccountLedgerIdentity" } } } } }, "CurrentAccountConfiguration": { "type": "object", "required": [ "public_id", "counterparty_type", "counterparty_public_id", "counterparty_name", "counterpart_administration", "restricted_counterpart", "denomination_currency_code", "status", "revision", "position" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "counterparty_type": { "type": "string", "enum": [ "contact", "administration" ] }, "counterparty_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "counterparty_name": { "type": [ "string", "null" ] }, "counterpart_administration": { "oneOf": [ { "$ref": "#/components/schemas/RelationContactIdentity" }, { "type": "null" } ] }, "restricted_counterpart": { "type": "boolean" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "status": { "type": "string", "enum": [ "draft", "ready", "inactive" ] }, "revision": { "type": "integer", "minimum": 1 }, "position": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountPositionConfiguration" }, { "type": "null" } ] } } }, "CurrentAccountConfigurationResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountConfiguration" } } }, "CurrentAccountConfigurationCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAccountConfiguration" } } } }, "CurrentAccountReachableCounterparty": { "type": "object", "required": [ "type", "public_id", "name", "minimum_hops", "usage_mode" ], "additionalProperties": false, "properties": { "type": { "type": "string", "const": "contact" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "minimum_hops": { "type": "integer", "minimum": 1, "maximum": 8 }, "usage_mode": { "type": "string", "enum": [ "normal", "settlement_only" ] } } }, "CurrentAccountReachableCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAccountReachableCounterparty" } } } }, "CurrentAccountReconciliationAccount": { "type": "object", "required": [ "ledger_account_public_id", "ledger_account_code", "ledger_account_name", "native_signed", "base_carrying_signed" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_code": { "type": "string" }, "ledger_account_name": { "type": "string" }, "native_signed": { "type": "string" }, "base_carrying_signed": { "type": "string" } } }, "CurrentAccountReconciliationPosition": { "type": "object", "required": [ "public_id", "administration_public_id", "denomination_currency_code", "position_signed", "position_kind", "accounts" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "position_signed": { "type": "string" }, "position_kind": { "type": "string", "enum": [ "zero", "receivable", "payable" ] }, "accounts": { "type": "object", "required": [ "receivable", "payable" ], "additionalProperties": false, "properties": { "receivable": { "$ref": "#/components/schemas/CurrentAccountReconciliationAccount" }, "payable": { "$ref": "#/components/schemas/CurrentAccountReconciliationAccount" } } } } }, "CurrentAccountReconciliation": { "type": "object", "required": [ "configuration_public_id", "denomination_currency_code", "positions", "difference", "matches" ], "additionalProperties": false, "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAccountReconciliationPosition" } }, "difference": { "type": "string" }, "matches": { "type": "boolean" } } }, "CurrentAccountReconciliationResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountReconciliation" } } }, "CurrentAccountLiveRouteNode": { "type": "object", "required": [ "type", "public_id", "name" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "administration", "contact" ] }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" } } }, "CurrentAccountLiveRouteEdge": { "type": "object", "required": [ "sequence", "configuration_public_id", "denomination_currency_code", "from_administration_public_id", "to_type", "to_public_id" ], "additionalProperties": false, "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 8 }, "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "from_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "to_type": { "type": "string", "enum": [ "administration", "contact" ] }, "to_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "CurrentAccountLiveRoute": { "type": "object", "required": [ "state_hash", "hops", "usage_mode", "configuration_public_ids", "nodes", "edges" ], "additionalProperties": false, "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "hops": { "type": "integer", "minimum": 1, "maximum": 8 }, "usage_mode": { "type": "string", "enum": [ "normal", "settlement_only" ] }, "configuration_public_ids": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/Ulid" } }, "nodes": { "type": "array", "minItems": 2, "maxItems": 9, "items": { "$ref": "#/components/schemas/CurrentAccountLiveRouteNode" } }, "edges": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountLiveRouteEdge" } } } }, "CurrentAccountPersistedRouteEdge": { "type": "object", "required": [ "sequence", "configuration_public_id", "denomination_currency_code", "native_amount" ], "additionalProperties": false, "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 8 }, "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" } } }, "CurrentAccountPersistedRoute": { "type": "object", "required": [ "state_hash", "hops", "edges" ], "additionalProperties": false, "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "hops": { "type": "integer", "minimum": 1, "maximum": 8 }, "edges": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountPersistedRouteEdge" } } } }, "CurrentAccountEmptyRoute": { "type": "array", "maxItems": 0 }, "CurrentAccountJournalEntryIdentity": { "type": "object", "required": [ "administration_public_id", "journal_entry_public_id", "status" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "journal_entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "posted", "deleted" ] } } }, "CurrentAccountPreviewFx": { "type": "object", "required": [ "native_currency_code", "native_amount", "converted_base_amount" ], "additionalProperties": false, "properties": { "native_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" }, "converted_base_amount": { "type": "string" } } }, "CurrentAccountPreviewGeneratedFxResult": { "type": "object", "required": [ "role", "source_account_public_id", "transaction_equivalent", "carrying_released", "amount" ], "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "realized_fx_gain", "realized_fx_loss" ] }, "source_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "transaction_equivalent": { "type": "string" }, "carrying_released": { "type": "string" }, "amount": { "type": "string" } } }, "CurrentAccountPreviewJournalLine": { "type": "object", "required": [ "ledger_account_public_id", "ledger_account_code", "ledger_account_name", "side", "amount", "fx", "generated_fx_result" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_code": { "type": "string" }, "ledger_account_name": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string" }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountPreviewFx" }, { "type": "null" } ] }, "generated_fx_result": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountPreviewGeneratedFxResult" }, { "type": "null" } ] } } }, "CurrentAccountPositionChange": { "type": "object", "required": [ "position_public_id", "configuration_public_id", "denomination_currency_code", "before", "after" ], "additionalProperties": false, "properties": { "position_public_id": { "$ref": "#/components/schemas/Ulid" }, "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "before": { "type": "string" }, "after": { "type": "string" } } }, "CurrentAccountPreviewJournalEntry": { "type": "object", "required": [ "administration_public_id", "administration_name", "currency_code", "fiscal_year_public_id", "entry_number", "lines", "total_debit", "total_credit", "position_changes" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_name": { "type": "string" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "entry_number": { "type": "string", "pattern": "^J[0-9]{6,}$" }, "lines": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/CurrentAccountPreviewJournalLine" } }, "total_debit": { "type": "string" }, "total_credit": { "type": "string" }, "position_changes": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAccountPositionChange" } } } }, "CurrentAccountBaseAmount": { "type": "object", "required": [ "administration_public_id", "base_amount" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "base_amount": { "type": "string" } } }, "CurrentAccountEdgeAmount": { "type": "object", "required": [ "configuration_public_id", "denomination_currency_code", "native_amount", "base_amounts" ], "additionalProperties": false, "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" }, "base_amounts": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "$ref": "#/components/schemas/CurrentAccountBaseAmount" } } } }, "CurrentAccountPreview": { "type": "object", "required": [ "state_hash", "route", "edge_amounts", "journal_entries" ], "additionalProperties": false, "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "route": { "$ref": "#/components/schemas/CurrentAccountLiveRoute" }, "edge_amounts": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountEdgeAmount" } }, "journal_entries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CurrentAccountPreviewJournalEntry" } }, "valuation_journals": { "type": "array", "description": "In-place updates to existing currency valuations, confirmed with the original transaction, including the original journal for comparison.", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "settlement_native_amount": { "type": "string" } } }, "CurrentAccountCommandTransaction": { "type": "object", "required": [ "public_id", "source_administration_public_id", "status", "revision", "target_type", "target_public_id", "posting_date", "description", "direction", "denomination_currency_code", "native_amount", "route", "journal_entries", "preview", "deleted_at" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "source_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "const": "posted" }, "revision": { "type": "integer", "minimum": 1 }, "target_type": { "type": "string", "const": "contact" }, "target_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" }, "route": { "$ref": "#/components/schemas/CurrentAccountLiveRoute" }, "journal_entries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CurrentAccountJournalEntryIdentity" } }, "preview": { "$ref": "#/components/schemas/CurrentAccountPreview" }, "deleted_at": { "type": "null" }, "provider_payout": { "type": "object", "additionalProperties": false, "required": [ "reference", "fee_settlement_public_id" ], "properties": { "reference": { "type": [ "string", "null" ] }, "fee_settlement_public_id": { "type": [ "string", "null" ] } } }, "settlement_native_amount": { "type": "string" }, "settlement_currency_code": { "type": "string" } } }, "CurrentAccountPersistedPostedTransaction": { "type": "object", "required": [ "public_id", "source_administration_public_id", "status", "revision", "target_type", "target_public_id", "posting_date", "description", "direction", "denomination_currency_code", "native_amount", "route", "journal_entries", "preview", "deleted_at", "restricted_route" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "source_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "const": "posted" }, "revision": { "type": "integer", "minimum": 1 }, "target_type": { "type": "string", "const": "contact" }, "target_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" }, "route": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountPersistedRoute" }, { "$ref": "#/components/schemas/CurrentAccountEmptyRoute" } ] }, "journal_entries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CurrentAccountJournalEntryIdentity" } }, "preview": { "type": "null" }, "deleted_at": { "type": "null" }, "restricted_route": { "type": "boolean" }, "provider_payout": { "type": "object", "additionalProperties": false, "required": [ "reference", "fee_settlement_public_id" ], "properties": { "reference": { "type": [ "string", "null" ] }, "fee_settlement_public_id": { "type": [ "string", "null" ] } } } } }, "CurrentAccountDeletedTransaction": { "type": "object", "required": [ "public_id", "source_administration_public_id", "status", "revision", "target_type", "target_public_id", "posting_date", "description", "direction", "denomination_currency_code", "native_amount", "route", "journal_entries", "deleted_at" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "source_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "const": "deleted" }, "revision": { "type": "integer", "minimum": 1 }, "target_type": { "type": "null" }, "target_public_id": { "type": "null" }, "posting_date": { "type": "null" }, "description": { "type": "null" }, "direction": { "type": "null" }, "denomination_currency_code": { "type": "null" }, "native_amount": { "type": "null" }, "route": { "$ref": "#/components/schemas/CurrentAccountEmptyRoute" }, "journal_entries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CurrentAccountJournalEntryIdentity" } }, "deleted_at": { "type": "string", "format": "date-time" } } }, "CurrentAccountPersistedDeletedTransaction": { "type": "object", "required": [ "public_id", "source_administration_public_id", "status", "revision", "target_type", "target_public_id", "posting_date", "description", "direction", "denomination_currency_code", "native_amount", "route", "journal_entries", "deleted_at", "restricted_route" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "source_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "const": "deleted" }, "revision": { "type": "integer", "minimum": 1 }, "target_type": { "type": "null" }, "target_public_id": { "type": "null" }, "posting_date": { "type": "null" }, "description": { "type": "null" }, "direction": { "type": "null" }, "denomination_currency_code": { "type": "null" }, "native_amount": { "type": "null" }, "route": { "$ref": "#/components/schemas/CurrentAccountEmptyRoute" }, "journal_entries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CurrentAccountJournalEntryIdentity" } }, "preview": { "type": "null" }, "deleted_at": { "type": "string", "format": "date-time" }, "restricted_route": { "type": "boolean" } } }, "CurrentAccountPersistedTransaction": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountPersistedPostedTransaction" }, { "$ref": "#/components/schemas/CurrentAccountPersistedDeletedTransaction" } ] }, "CurrentAccountCommandTransactionResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountCommandTransaction" } } }, "CurrentAccountPersistedTransactionResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountPersistedTransaction" } } }, "CurrentAccountDeletedTransactionResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountDeletedTransaction" } } }, "CurrentAccountTransactionCollection": { "type": "object", "required": [ "data", "links" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAccountPersistedTransaction" } }, "links": { "type": "object", "required": [ "next" ], "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ] } } } } }, "CurrentAccountPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountPreview" } } }, "CurrentAccountDataResponse": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountConfigurationResponse" }, { "$ref": "#/components/schemas/CurrentAccountCommandTransactionResponse" }, { "$ref": "#/components/schemas/CurrentAccountPersistedTransactionResponse" }, { "$ref": "#/components/schemas/CurrentAccountDeletedTransactionResponse" }, { "$ref": "#/components/schemas/CurrentAccountPreviewResponse" } ] }, "VatRate": { "type": "object", "required": [ "numerator", "denominator", "fraction" ], "additionalProperties": false, "properties": { "numerator": { "type": "string", "pattern": "^[0-9]+$" }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "fraction": { "type": "string", "pattern": "^[0-9]+/[1-9][0-9]*$" } } }, "VatTreatment": { "type": "object", "required": [ "code", "label", "description", "direction", "display_group", "display_group_label", "display_order", "territory", "counterparty_type", "supply_type", "mechanism", "calculation_mode", "rate", "required_context", "valid_from", "valid_until", "treatment_version" ], "additionalProperties": false, "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "label": { "type": "string" }, "description": { "type": "string" }, "direction": { "type": "string", "enum": [ "sale", "purchase", "adjustment" ] }, "display_group": { "type": "string" }, "display_group_label": { "type": "string" }, "display_order": { "type": "integer", "minimum": 1 }, "territory": { "type": "string", "enum": [ "nl", "eu", "non_eu", "country_specific", "none" ] }, "counterparty_type": { "type": "string", "enum": [ "b2b", "b2c", "any", "none" ] }, "supply_type": { "type": "string", "enum": [ "goods", "services", "digital_services", "adjustment", "any" ] }, "mechanism": { "type": "string", "enum": [ "normal", "zero_rate", "exempt", "reverse_charge", "intra_eu_supply", "intra_eu_acquisition", "distance_sale", "export", "import", "article_23", "margin", "foreign_vat", "private_use" ] }, "calculation_mode": { "type": "string", "enum": [ "automatic", "manual", "none", "margin", "destination_rate" ] }, "rate": { "oneOf": [ { "$ref": "#/components/schemas/VatRate" }, { "type": "null" } ] }, "required_context": { "type": "array", "items": { "type": "string" } }, "valid_from": { "type": "string", "format": "date" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "treatment_version": { "type": "integer", "minimum": 1 } } }, "VatTreatmentCatalog": { "type": "object", "required": [ "dataset_version", "requested_on", "direction", "treatments" ], "additionalProperties": false, "properties": { "dataset_version": { "type": "string", "const": "v2" }, "requested_on": { "type": "string", "format": "date" }, "direction": { "type": "string", "enum": [ "sale", "purchase", "adjustment" ] }, "treatments": { "type": "array", "items": { "$ref": "#/components/schemas/VatTreatment" } } } }, "VatTreatmentCatalogResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/VatTreatmentCatalog" } } }, "FiscalYear": { "type": "object", "required": [ "public_id", "starts_on", "ends_on", "label", "status" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "closed" ] } } }, "FiscalYearResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FiscalYear" } } }, "FiscalYearCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } } } }, "FiscalYearClosingIdentity": { "type": "object", "required": [ "public_id", "label", "starts_on", "ends_on", "status" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "label": { "type": "string" }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "open", "closed" ] } } }, "DerivedFiscalYearResult": { "type": "object", "required": [ "key", "source", "amount", "side", "kind" ], "additionalProperties": false, "properties": { "key": { "type": "string", "enum": [ "current_year_result", "prior_year_results" ] }, "source": { "type": "string", "const": "derived" }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,4})?$" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "kind": { "type": "string", "enum": [ "profit", "loss", "zero" ] } } }, "FiscalYearClosingReconciliation": { "type": "object", "required": [ "is_balanced", "difference" ], "additionalProperties": false, "properties": { "is_balanced": { "type": "boolean" }, "difference": { "$ref": "#/components/schemas/SignedBalance" } } }, "FiscalYearClosingNotice": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "FiscalYearClosingPreview": { "type": "object", "required": [ "fiscal_year", "as_of_date", "currency_code", "current_year_result", "prior_year_results", "reconciliation", "close_eligible", "blockers", "warnings", "broker" ], "additionalProperties": false, "properties": { "fiscal_year": { "$ref": "#/components/schemas/FiscalYearClosingIdentity" }, "as_of_date": { "type": "string", "format": "date" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "current_year_result": { "$ref": "#/components/schemas/DerivedFiscalYearResult" }, "prior_year_results": { "$ref": "#/components/schemas/DerivedFiscalYearResult" }, "reconciliation": { "$ref": "#/components/schemas/FiscalYearClosingReconciliation" }, "close_eligible": { "type": "boolean" }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYearClosingNotice" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYearClosingNotice" } }, "broker": { "type": "object", "required": [ "positions", "monetary", "cash" ], "additionalProperties": false, "properties": { "positions": { "type": [ "object", "null" ], "required": [ "date", "currency_code", "accounts", "reconciled" ], "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "currency_code": { "type": "string" }, "reconciled": { "type": "boolean" }, "accounts": { "type": "array", "items": { "type": "object", "required": [ "ledger_account_public_id", "number", "name", "ledger", "registered", "difference" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "name": { "type": "string" }, "ledger": { "type": "string" }, "registered": { "type": "string" }, "difference": { "type": "string" }, "currency_code": { "type": "string" }, "native_ledger": { "type": "string" }, "native_registered": { "type": "string" }, "native_difference": { "type": "string" } } } } } }, "monetary": { "type": [ "object", "null" ], "required": [ "date", "currency_code", "accounts", "reconciled" ], "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "currency_code": { "type": "string" }, "reconciled": { "type": "boolean" }, "accounts": { "type": "array", "items": { "type": "object", "required": [ "ledger_account_public_id", "number", "name", "ledger", "registered", "difference" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "name": { "type": "string" }, "ledger": { "type": "string" }, "registered": { "type": "string" }, "difference": { "type": "string" }, "currency_code": { "type": "string" }, "native_ledger": { "type": "string" }, "native_registered": { "type": "string" }, "native_difference": { "type": "string" } } } } } }, "cash": { "type": [ "object", "null" ], "required": [ "date", "currency_code", "accounts", "reconciled" ], "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "currency_code": { "type": "string" }, "reconciled": { "type": "boolean" }, "accounts": { "type": "array", "items": { "type": "object", "required": [ "ledger_account_public_id", "number", "name", "currency_code", "ledger", "native_ledger", "broker_movements", "posted_broker_movements", "movement_difference", "mismatched_settlements", "shared_with_bank" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "name": { "type": "string" }, "currency_code": { "type": "string" }, "ledger": { "type": "string" }, "native_ledger": { "type": "string" }, "broker_movements": { "type": "string" }, "posted_broker_movements": { "type": "string" }, "movement_difference": { "type": "string" }, "mismatched_settlements": { "type": "integer", "minimum": 0 }, "shared_with_bank": { "type": "boolean" } } } } } } }, "description": "Dated source-to-ledger reconciliation; null on a calculation error. This is not proof that an external broker statement was checked." } } }, "FiscalYearClosingPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FiscalYearClosingPreview" } } }, "CreateFiscalYearRequest": { "oneOf": [ { "type": "object", "required": [ "ends_on" ], "additionalProperties": false, "properties": { "ends_on": { "type": "string", "format": "date" }, "calendar_values": { "$ref": "#/components/schemas/FiscalCalendarValues" } } }, { "$ref": "#/components/schemas/FiscalCalendarConfirmation" } ] }, "UpdateFiscalYearRequest": { "oneOf": [ { "type": "object", "required": [ "starts_on", "ends_on" ], "additionalProperties": false, "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "calendar_values": { "$ref": "#/components/schemas/FiscalCalendarValues" } } }, { "$ref": "#/components/schemas/FiscalCalendarConfirmation" } ] }, "AdjustBoundaryRequest": { "oneOf": [ { "type": "object", "required": [ "boundary_date" ], "additionalProperties": false, "properties": { "boundary_date": { "type": "string", "format": "date" }, "calendar_values": { "$ref": "#/components/schemas/FiscalCalendarValues" } } }, { "$ref": "#/components/schemas/FiscalCalendarConfirmation" } ] }, "BoundaryResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "earlier", "later" ], "additionalProperties": false, "properties": { "earlier": { "$ref": "#/components/schemas/FiscalYear" }, "later": { "$ref": "#/components/schemas/FiscalYear" } } } } }, "LocalizedCatalogItem": { "type": "object", "required": [ "code", "label" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" } } }, "ReportingGroup": { "type": "object", "required": [ "code", "label", "statement" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "statement": { "type": "string", "enum": [ "balance", "profit_and_loss" ] } } }, "RgsReference": { "type": "object", "required": [ "version", "reference_code", "reference_number", "description" ], "additionalProperties": false, "properties": { "version": { "type": "string", "examples": [ "3.8" ] }, "reference_code": { "type": "string" }, "reference_number": { "type": [ "string", "null" ] }, "description": { "type": "string" } } }, "LedgerAccount": { "type": "object", "required": [ "public_id", "code", "name", "reporting_classification", "reporting_group", "normal_balance", "status", "currency_mode", "native_currency_code", "purchase_vat_deduction_percentage", "rgs" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string", "pattern": "^[A-Z0-9]{1,10}$" }, "name": { "type": "string", "maxLength": 255 }, "reporting_classification": { "$ref": "#/components/schemas/LocalizedCatalogItem" }, "reporting_group": { "$ref": "#/components/schemas/ReportingGroup" }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "currency_mode": { "type": "string", "enum": [ "base_only", "fixed_foreign" ] }, "native_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "purchase_vat_deduction_percentage": { "$ref": "#/components/schemas/PurchaseVatDeductionPreset" }, "rgs": { "oneOf": [ { "$ref": "#/components/schemas/RgsReference" }, { "type": "null" } ] } } }, "LedgerAccountResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LedgerAccount" } } }, "LedgerAccountCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerAccount" } } } }, "LedgerAccountRgsInput": { "type": "object", "required": [ "version", "reference_code" ], "additionalProperties": false, "properties": { "version": { "type": "string", "maxLength": 16 }, "reference_code": { "type": "string", "maxLength": 20 } } }, "PurchaseVatDeductionPreset": { "type": [ "string", "null" ], "pattern": "^(?:100(?:\\.0{1,4})?|(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,4})?)$", "description": "Optional identity-bound suggestion for the VAT deduction percentage of new purchase lines. Null means no suggestion. Omission on create stores null; omission on update preserves the current value. Setting null explicitly removes the suggestion. It never changes recorded purchase lines.", "examples": [ "100.0000", "0.0000", "75.2500", null ] }, "CreateLedgerAccountRequest": { "type": "object", "required": [ "code", "name", "reporting_classification_code" ], "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 10 }, "name": { "type": "string", "maxLength": 255 }, "reporting_classification_code": { "type": "string", "maxLength": 64 }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "currency_mode": { "type": "string", "enum": [ "base_only", "fixed_foreign" ], "default": "base_only" }, "native_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "purchase_vat_deduction_percentage": { "$ref": "#/components/schemas/PurchaseVatDeductionPreset" }, "rgs": { "oneOf": [ { "$ref": "#/components/schemas/LedgerAccountRgsInput" }, { "type": "null" } ] } } }, "UpdateLedgerAccountRequest": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 10 }, "name": { "type": "string", "maxLength": 255 }, "reporting_classification_code": { "type": "string", "maxLength": 64 }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "currency_mode": { "type": "string", "enum": [ "base_only", "fixed_foreign" ] }, "native_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "purchase_vat_deduction_percentage": { "$ref": "#/components/schemas/PurchaseVatDeductionPreset" }, "rgs": { "oneOf": [ { "$ref": "#/components/schemas/LedgerAccountRgsInput" }, { "type": "null" } ] } } }, "JournalEntryFiscalYear": { "type": "object", "required": [ "public_id", "label" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "label": { "type": "string" } } }, "JournalEntryLine": { "type": "object", "required": [ "line_number", "ledger_account", "side", "amount", "foreign_currency", "foreign_amount", "affects_native_balance", "valuation_basis", "transaction_equivalent", "carrying_release", "settlement_evidence", "generated_fx_result", "applied_rates" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer", "minimum": 1, "maximum": 500 }, "ledger_account": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,4})?$", "description": "Zero only for a proven positive native movement. Foreign cash retains its actual rate evidence; exact administration-currency base_cash has no fictitious same-currency rate.", "examples": [ "100.00", "0.00" ] }, "foreign_currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "foreign_amount": { "type": [ "string", "null" ], "pattern": "^(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,12})?$", "description": "Original native amount. The legacy field name also covers exact administration-currency base_cash; new monetary facts retain up to twelve decimals without cent rounding." }, "affects_native_balance": { "type": [ "boolean", "null" ] }, "valuation_basis": { "type": [ "string", "null" ] }, "transaction_equivalent": { "type": [ "string", "null" ] }, "carrying_release": { "type": [ "string", "null" ] }, "settlement_evidence": { "oneOf": [ { "$ref": "#/components/schemas/FxSettlementEvidence" }, { "type": "null" } ] }, "generated_fx_result": { "oneOf": [ { "$ref": "#/components/schemas/GeneratedFxResult" }, { "type": "null" } ] }, "applied_rates": { "type": "array", "items": { "$ref": "#/components/schemas/AppliedFxRate" } }, "cash_conversion": { "type": [ "object", "null" ], "description": "Original conversion evidence when a periodic cash line retains an explicit source conversion. This is stored input, not a newly calculated exchange rate.", "required": [ "snapshot", "input_mode", "purposes" ], "additionalProperties": false, "properties": { "snapshot": { "type": "object", "description": "Stored applied-rate evidence of the original source." }, "input_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "purposes": { "type": "array", "items": { "type": "string" } } } }, "claim_identity": { "type": [ "object", "null" ], "description": "Existing source identity when a claim or a carrying-value transfer exposes its underlying claim.", "required": [ "administration_id", "source_public_id", "component_id", "ledger_account_id", "role" ], "additionalProperties": false, "properties": { "administration_id": { "type": "integer" }, "source_public_id": { "type": "string" }, "source_revision": { "type": "integer", "minimum": 1 }, "claim_revision": { "type": "integer", "minimum": 1 }, "component_id": { "type": "string" }, "ledger_account_id": { "type": "integer" }, "role": { "type": "string" } } }, "opening_trade_item_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "JournalEntrySummaryBase": { "type": "object", "required": [ "public_id", "number", "revision", "source_type", "currency_code", "created_at", "updated_at" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string", "pattern": "^J[0-9]{6,}$", "examples": [ "J000143" ] }, "revision": { "type": "integer", "minimum": 1 }, "source_type": { "type": [ "string", "null" ], "enum": [ "loan", "manual_journal", "fx_revaluation", "fx_periodic_adjustment", "rekening_courant", "bank_transfer", "sales_document", "sales_settlement", "purchase_document", "purchase_settlement", "purchase_vat_correction", "vat_special_fact", "vat_return", "vat_return_payment", "asset_depreciation", "asset_adjustment", "asset_disposal", "investment_event", "broker_valuation_month", "bank_owner_movement", "broker_shares", "broker_currency_exchange", "broker_group_valuation", "sales_write_off", null, "bank_tax_movement", "bank_opening_private", "bank_balance_movement" ] }, "currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "JournalEntryPostedState": { "type": "object", "required": [ "posting_date", "fiscal_year", "description", "status", "currency_code", "total_amount", "deleted_at" ], "properties": { "posting_date": { "type": "string", "format": "date" }, "fiscal_year": { "$ref": "#/components/schemas/JournalEntryFiscalYear" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "const": "posted" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "total_amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,4})?$", "description": "May be zero for a journal consisting exclusively of native-only FX movements.", "examples": [ "100.00", "0.00" ] }, "deleted_at": { "type": "null" } } }, "JournalEntryDeletedState": { "type": "object", "required": [ "posting_date", "fiscal_year", "description", "status", "currency_code", "total_amount", "deleted_at" ], "properties": { "posting_date": { "type": "null" }, "fiscal_year": { "type": "null" }, "description": { "type": "null" }, "status": { "type": "string", "const": "deleted" }, "currency_code": { "type": "null" }, "total_amount": { "type": "null" }, "deleted_at": { "type": "string", "format": "date-time" } } }, "PostedJournalEntrySummary": { "allOf": [ { "$ref": "#/components/schemas/JournalEntrySummaryBase" }, { "$ref": "#/components/schemas/JournalEntryPostedState" } ], "unevaluatedProperties": false }, "DeletedJournalEntrySummary": { "allOf": [ { "$ref": "#/components/schemas/JournalEntrySummaryBase" }, { "$ref": "#/components/schemas/JournalEntryDeletedState" } ], "unevaluatedProperties": false }, "JournalEntrySummary": { "oneOf": [ { "$ref": "#/components/schemas/PostedJournalEntrySummary" }, { "$ref": "#/components/schemas/DeletedJournalEntrySummary" }, { "$ref": "#/components/schemas/NoDifferenceJournalEntrySummary" } ], "discriminator": { "propertyName": "status", "mapping": { "posted": "#/components/schemas/PostedJournalEntrySummary", "deleted": "#/components/schemas/DeletedJournalEntrySummary", "no_difference": "#/components/schemas/NoDifferenceJournalEntrySummary" } } }, "PostedJournalEntry": { "allOf": [ { "$ref": "#/components/schemas/JournalEntrySummaryBase" }, { "$ref": "#/components/schemas/JournalEntryPostedState" }, { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/JournalEntryLine" }, "allOf": [ { "if": { "maxItems": 1 }, "then": { "items": { "properties": { "amount": { "pattern": "^0(?:\\.0+)?$" }, "affects_native_balance": { "const": true }, "foreign_currency": { "type": "string" }, "foreign_amount": { "type": "string", "pattern": "^(?!0(?:\\.0+)?$)(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$" }, "applied_rates": { "minItems": 1 } } } } } ] } } } ], "unevaluatedProperties": false }, "DeletedJournalEntry": { "allOf": [ { "$ref": "#/components/schemas/JournalEntrySummaryBase" }, { "$ref": "#/components/schemas/JournalEntryDeletedState" }, { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "maxItems": 0, "items": { "$ref": "#/components/schemas/JournalEntryLine" } } } } ], "unevaluatedProperties": false }, "JournalEntry": { "oneOf": [ { "$ref": "#/components/schemas/PostedJournalEntry" }, { "$ref": "#/components/schemas/DeletedJournalEntry" }, { "$ref": "#/components/schemas/NoDifferenceJournalEntry" } ], "discriminator": { "propertyName": "status", "mapping": { "posted": "#/components/schemas/PostedJournalEntry", "deleted": "#/components/schemas/DeletedJournalEntry", "no_difference": "#/components/schemas/NoDifferenceJournalEntry" } } }, "JournalEntryResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/JournalEntry" } } }, "PostedJournalEntryResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PostedJournalEntry" } } }, "DeletedJournalEntryResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedJournalEntry" } } }, "JournalEntryCollection": { "type": "object", "required": [ "data", "links", "meta" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntrySummary" } }, "links": { "type": "object", "required": [ "next" ], "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ], "format": "uri" } } }, "meta": { "type": "object", "required": [ "per_page" ], "additionalProperties": false, "properties": { "per_page": { "type": "integer", "minimum": 1, "maximum": 100 } } } } }, "JournalEntryLineInput": { "type": "object", "required": [ "ledger_account_public_id", "side", "amount" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "maxLength": 32, "pattern": "^(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,4})?$", "description": "Positive in administration-currency precision, except a fixed-foreign account movement with positive native amount and positive explicit rate rounding exactly to zero. No client native_only flag is accepted." }, "fx": { "$ref": "#/components/schemas/ManualFxConversionInput" }, "settlement_evidence": { "$ref": "#/components/schemas/FxSettlementEvidence" }, "opening_trade_item_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Optional payable opening-item association. Null explicitly removes a link. Omission retains an existing link only with unambiguous unchanged line correspondence. Requires purchases:write in addition to journal_entries:write." } }, "allOf": [ { "if": { "properties": { "amount": { "pattern": "^0(?:\\.0+)?$" } } }, "then": { "required": [ "fx" ], "properties": { "fx": { "required": [ "rate" ], "properties": { "conversion_mode": { "const": "rate" } } } } } } ] }, "JournalEntryLinesInput": { "description": "Normally 2 to 500 balanced lines. One line is accepted only for a fully validated native-only FX movement whose entered base amount is zero; fixed-foreign account, native currency, positive rate and exact rounding are checked server-side.", "oneOf": [ { "type": "array", "minItems": 2, "maxItems": 500, "items": { "$ref": "#/components/schemas/JournalEntryLineInput" } }, { "type": "array", "minItems": 1, "maxItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/JournalEntryLineInput" }, { "properties": { "amount": { "pattern": "^0(?:\\.0+)?$" } } } ] } } ] }, "PostJournalEntryRequest": { "type": "object", "required": [ "posting_date", "description", "lines" ], "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "lines": { "$ref": "#/components/schemas/JournalEntryLinesInput" }, "fx_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Optional explicit placement for a new foreign-cash journal on the same account/day. The anchor is validated even when that day has no saved order. Existing edit routes do not accept this create-only field." } } }, "JournalFxPreviewRequest": { "type": "object", "required": [ "posting_date", "description", "lines" ], "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "lines": { "$ref": "#/components/schemas/JournalEntryLinesInput" }, "journal_entry_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "EditJournalEntryRequest": { "type": "object", "required": [ "expected_revision", "posting_date", "description", "lines" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "lines": { "$ref": "#/components/schemas/JournalEntryLinesInput" }, "fx_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "DeleteJournalEntryRequest": { "type": "object", "required": [ "expected_revision" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } }, "LedgerAccountReference": { "type": "object", "required": [ "public_id", "code", "name", "normal_balance", "status", "currency_mode", "native_currency_code" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "currency_mode": { "type": "string", "enum": [ "base_only", "fixed_foreign" ] }, "native_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" } } }, "SignedBalance": { "type": "object", "required": [ "amount", "side" ], "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,4})?$" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] } } }, "LedgerPeriod": { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "GeneralLedgerAccount": { "type": "object", "required": [ "ledger_account", "balance", "native_balance", "last_mutation", "mutation_count" ], "additionalProperties": false, "properties": { "ledger_account": { "$ref": "#/components/schemas/LedgerAccountReference" }, "balance": { "$ref": "#/components/schemas/SignedBalance" }, "native_balance": { "oneOf": [ { "$ref": "#/components/schemas/NativeSignedBalance" }, { "type": "null" } ] }, "last_mutation": { "type": [ "string", "null" ], "format": "date" }, "mutation_count": { "type": "integer", "minimum": 0 }, "physical_balance": { "$ref": "#/components/schemas/SignedBalance" }, "calculated_balance": { "$ref": "#/components/schemas/SignedBalance" } } }, "GeneralLedgerData": { "type": "object", "required": [ "currency_code", "fiscal_year", "period", "accounts" ], "additionalProperties": false, "properties": { "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "period": { "$ref": "#/components/schemas/LedgerPeriod" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralLedgerAccount" } }, "broker_reconciliation": { "$ref": "#/components/schemas/BrokerCalculatedReportReconciliation" } } }, "CursorLinks": { "type": "object", "required": [ "next" ], "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ], "format": "uri" } } }, "CursorMeta": { "type": "object", "required": [ "per_page" ], "additionalProperties": false, "properties": { "per_page": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "GeneralLedgerResponse": { "type": "object", "required": [ "data", "links", "meta" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/GeneralLedgerData" }, "links": { "$ref": "#/components/schemas/CursorLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } } }, "GeneralLedgerLine": { "type": "object", "required": [ "source", "date", "number", "journal_entry_public_id", "description", "line_number", "debit", "credit", "balance", "source_type", "revaluation_public_id", "foreign_currency", "native_mutation", "native_balance", "transaction_equivalent", "carrying_release", "effective_carrying_rate", "applied_rate" ], "additionalProperties": false, "properties": { "source": { "type": "string", "enum": [ "opening_balance", "journal_entry", "calculated_broker_reconciliation" ] }, "date": { "type": "string", "format": "date" }, "number": { "type": [ "string", "null" ] }, "journal_entry_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "description": { "type": "string" }, "line_number": { "type": [ "integer", "null" ], "minimum": 1 }, "debit": { "type": [ "string", "null" ] }, "credit": { "type": [ "string", "null" ] }, "balance": { "$ref": "#/components/schemas/SignedBalance" }, "source_type": { "type": [ "string", "null" ] }, "revaluation_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "foreign_currency": { "type": [ "string", "null" ] }, "native_mutation": { "oneOf": [ { "$ref": "#/components/schemas/NativeMutation" }, { "type": "null" } ] }, "native_balance": { "oneOf": [ { "$ref": "#/components/schemas/NativeSignedBalance" }, { "type": "null" } ] }, "transaction_equivalent": { "type": [ "string", "null" ] }, "carrying_release": { "type": [ "string", "null" ] }, "effective_carrying_rate": { "type": [ "string", "null" ] }, "applied_rate": { "oneOf": [ { "$ref": "#/components/schemas/CompactFxRate" }, { "type": "null" } ] }, "calculated_key": { "type": "string", "pattern": "^broker-cutoff:", "description": "Stable report-only cutoff identity. Present only on a calculated reconciliation; never a journal identity." } } }, "GeneralLedgerCardData": { "type": "object", "required": [ "currency_code", "fiscal_year", "period", "ledger_account", "beginning_balance", "closing_balance", "beginning_native_balance", "closing_native_balance", "mutation_count", "lines" ], "additionalProperties": false, "properties": { "currency_code": { "type": "string" }, "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "period": { "$ref": "#/components/schemas/LedgerPeriod" }, "ledger_account": { "$ref": "#/components/schemas/LedgerAccountReference" }, "beginning_balance": { "$ref": "#/components/schemas/SignedBalance" }, "closing_balance": { "$ref": "#/components/schemas/SignedBalance" }, "beginning_native_balance": { "oneOf": [ { "$ref": "#/components/schemas/NativeSignedBalance" }, { "type": "null" } ] }, "closing_native_balance": { "oneOf": [ { "$ref": "#/components/schemas/NativeSignedBalance" }, { "type": "null" } ] }, "mutation_count": { "type": "integer", "minimum": 0 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralLedgerLine" } }, "broker_reconciliation": { "$ref": "#/components/schemas/BrokerCalculatedReportReconciliation" } } }, "GeneralLedgerCardResponse": { "type": "object", "required": [ "data", "links", "meta" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/GeneralLedgerCardData" }, "links": { "$ref": "#/components/schemas/CursorLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } } }, "ReportMoney": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,4})?$", "description": "Exact stored amount: currency minor digits are the minimum; significant extra decimals from historical conversions are preserved, up to four. No rounding is applied to totals or reconciliation.", "examples": [ "1250.00", "-42.50", "82.6364", "0.0064" ] }, "ReportPeriod": { "type": "object", "required": [ "date_from", "date_to" ], "additionalProperties": false, "properties": { "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" } } }, "ReportLedgerAccount": { "type": "object", "required": [ "public_id", "code", "name", "status", "normal_balance" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] } } }, "ReportGroupReference": { "type": "object", "required": [ "code", "label", "statement" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "statement": { "type": "string", "enum": [ "balance", "profit_and_loss" ] } } }, "ReportClassificationReference": { "type": "object", "required": [ "code", "label" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" } } }, "DebitCreditColumns": { "type": "object", "required": [ "signed_amount", "debit", "credit" ], "additionalProperties": false, "properties": { "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "debit": { "$ref": "#/components/schemas/ReportMoney" }, "credit": { "$ref": "#/components/schemas/ReportMoney" } } }, "SignedReportResult": { "type": "object", "required": [ "signed_amount", "amount", "side", "kind" ], "additionalProperties": false, "properties": { "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "amount": { "$ref": "#/components/schemas/ReportMoney" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "kind": { "type": "string", "enum": [ "profit", "loss", "zero" ] } } }, "TrialBalanceAccountRow": { "type": "object", "required": [ "row_type", "ledger_account", "reporting_group", "reporting_classification", "beginning", "movements", "closing" ], "additionalProperties": false, "properties": { "row_type": { "type": "string", "const": "ledger_account" }, "ledger_account": { "$ref": "#/components/schemas/ReportLedgerAccount" }, "reporting_group": { "$ref": "#/components/schemas/ReportGroupReference" }, "reporting_classification": { "$ref": "#/components/schemas/ReportClassificationReference" }, "beginning": { "$ref": "#/components/schemas/DebitCreditColumns" }, "movements": { "$ref": "#/components/schemas/DebitCreditColumns" }, "closing": { "$ref": "#/components/schemas/DebitCreditColumns" } } }, "TrialBalanceDerivedRow": { "type": "object", "required": [ "row_type", "key", "source", "label", "signed_amount", "amount", "side", "kind", "beginning", "movements", "closing" ], "additionalProperties": false, "properties": { "row_type": { "type": "string", "const": "derived" }, "key": { "type": "string", "const": "prior_year_results" }, "source": { "type": "string", "const": "derived" }, "label": { "type": "string" }, "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "amount": { "$ref": "#/components/schemas/ReportMoney" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "kind": { "type": "string", "enum": [ "profit", "loss", "zero" ] }, "beginning": { "$ref": "#/components/schemas/DebitCreditColumns" }, "movements": { "$ref": "#/components/schemas/DebitCreditColumns" }, "closing": { "$ref": "#/components/schemas/DebitCreditColumns" } } }, "TrialBalanceTotals": { "type": "object", "required": [ "debit", "credit", "signed_difference", "is_balanced" ], "additionalProperties": false, "properties": { "debit": { "$ref": "#/components/schemas/ReportMoney" }, "credit": { "$ref": "#/components/schemas/ReportMoney" }, "signed_difference": { "$ref": "#/components/schemas/ReportMoney" }, "is_balanced": { "type": "boolean" } } }, "TrialBalanceReport": { "type": "object", "required": [ "report_type", "currency_code", "fiscal_year", "period", "include_zero", "rows", "totals" ], "additionalProperties": false, "properties": { "report_type": { "type": "string", "const": "trial_balance" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "period": { "$ref": "#/components/schemas/ReportPeriod" }, "include_zero": { "type": "boolean" }, "rows": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TrialBalanceAccountRow" }, { "$ref": "#/components/schemas/TrialBalanceDerivedRow" } ] } }, "totals": { "type": "object", "required": [ "beginning", "movements", "closing" ], "additionalProperties": false, "properties": { "beginning": { "$ref": "#/components/schemas/TrialBalanceTotals" }, "movements": { "$ref": "#/components/schemas/TrialBalanceTotals" }, "closing": { "$ref": "#/components/schemas/TrialBalanceTotals" } } }, "broker_reconciliation": { "$ref": "#/components/schemas/BrokerCalculatedReportReconciliation" }, "annual_cost_warnings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "document_public_id", "number", "posting_date", "due" ], "properties": { "code": { "const": "purchase_annual_costs_pending" }, "document_public_id": { "type": "string" }, "number": { "type": "string" }, "posting_date": { "type": "string", "format": "date" }, "due": { "type": "boolean" } } } } } }, "TrialBalanceReportResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TrialBalanceReport" } } }, "StatementAccountRow": { "type": "object", "required": [ "row_type", "ledger_account", "reporting_group", "reporting_classification", "signed_amount", "presentation_amount" ], "additionalProperties": false, "properties": { "row_type": { "type": "string", "const": "ledger_account" }, "ledger_account": { "$ref": "#/components/schemas/ReportLedgerAccount" }, "reporting_group": { "$ref": "#/components/schemas/ReportGroupReference" }, "reporting_classification": { "$ref": "#/components/schemas/ReportClassificationReference" }, "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "presentation_amount": { "$ref": "#/components/schemas/ReportMoney" }, "native_balance": { "type": "object", "required": [ "currency_code", "signed_amount", "amount", "side" ], "additionalProperties": false, "properties": { "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "signed_amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]{1,12})?$" }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] } } } } }, "StatementClassification": { "type": "object", "required": [ "code", "label", "accounts", "total" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/StatementAccountRow" } }, "total": { "type": "object", "required": [ "presentation_amount" ], "additionalProperties": false, "properties": { "presentation_amount": { "$ref": "#/components/schemas/ReportMoney" } } } } }, "StatementGroup": { "type": "object", "required": [ "code", "label", "statement", "classifications", "total" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "statement": { "type": "string", "const": "balance" }, "classifications": { "type": "array", "items": { "$ref": "#/components/schemas/StatementClassification" } }, "total": { "type": "object", "required": [ "presentation_amount" ], "additionalProperties": false, "properties": { "presentation_amount": { "$ref": "#/components/schemas/ReportMoney" } } } } }, "BalanceDerivedRow": { "type": "object", "required": [ "row_type", "key", "source", "label", "signed_amount", "amount", "side", "kind", "presentation_amount" ], "additionalProperties": false, "properties": { "row_type": { "type": "string", "const": "derived" }, "key": { "type": "string", "enum": [ "prior_year_results", "current_year_result" ] }, "source": { "type": "string", "const": "derived" }, "label": { "type": "string" }, "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "amount": { "$ref": "#/components/schemas/ReportMoney" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "kind": { "type": "string", "enum": [ "profit", "loss", "zero" ] }, "presentation_amount": { "$ref": "#/components/schemas/ReportMoney" } } }, "BalanceSheetSide": { "type": "object", "required": [ "key", "label", "groups", "derived_rows" ], "additionalProperties": false, "properties": { "key": { "type": "string", "enum": [ "assets", "liabilities_and_equity" ] }, "label": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/StatementGroup" } }, "derived_rows": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceDerivedRow" } } } }, "BalanceSheetReport": { "type": "object", "required": [ "report_type", "currency_code", "fiscal_year", "as_of", "include_zero", "sides", "totals", "technical_reconciliation" ], "additionalProperties": false, "properties": { "report_type": { "type": "string", "const": "balance_sheet" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "as_of": { "type": "string", "format": "date" }, "include_zero": { "type": "boolean" }, "sides": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/BalanceSheetSide" } }, "totals": { "type": "object", "required": [ "assets", "liabilities_and_equity", "difference", "is_balanced" ], "additionalProperties": false, "properties": { "assets": { "$ref": "#/components/schemas/ReportMoney" }, "liabilities_and_equity": { "$ref": "#/components/schemas/ReportMoney" }, "difference": { "$ref": "#/components/schemas/ReportMoney" }, "is_balanced": { "type": "boolean" } } }, "technical_reconciliation": { "type": "object", "required": [ "is_balanced", "difference" ], "additionalProperties": false, "properties": { "is_balanced": { "type": "boolean" }, "difference": { "type": "object", "required": [ "signed_amount", "amount", "side" ], "additionalProperties": false, "properties": { "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "amount": { "$ref": "#/components/schemas/ReportMoney" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] } } } } }, "broker_reconciliation": { "$ref": "#/components/schemas/BrokerCalculatedReportReconciliation" }, "annual_cost_warnings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "document_public_id", "number", "posting_date", "due" ], "properties": { "code": { "const": "purchase_annual_costs_pending" }, "document_public_id": { "type": "string" }, "number": { "type": "string" }, "posting_date": { "type": "string", "format": "date" }, "due": { "type": "boolean" } } } } } }, "BalanceSheetReportResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BalanceSheetReport" } } }, "ProfitAndLossAccountRow": { "type": "object", "required": [ "row_type", "ledger_account", "reporting_group", "reporting_classification", "debit", "credit", "signed_amount", "display_amount", "result_effect" ], "additionalProperties": false, "properties": { "row_type": { "type": "string", "const": "ledger_account" }, "ledger_account": { "$ref": "#/components/schemas/ReportLedgerAccount" }, "reporting_group": { "$ref": "#/components/schemas/ReportGroupReference" }, "reporting_classification": { "$ref": "#/components/schemas/ReportClassificationReference" }, "debit": { "$ref": "#/components/schemas/ReportMoney" }, "credit": { "$ref": "#/components/schemas/ReportMoney" }, "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "display_amount": { "$ref": "#/components/schemas/ReportMoney" }, "result_effect": { "$ref": "#/components/schemas/ReportMoney" } } }, "ProfitAndLossTotals": { "type": "object", "required": [ "debit", "credit", "signed_amount", "display_amount" ], "additionalProperties": false, "properties": { "debit": { "$ref": "#/components/schemas/ReportMoney" }, "credit": { "$ref": "#/components/schemas/ReportMoney" }, "signed_amount": { "$ref": "#/components/schemas/ReportMoney" }, "display_amount": { "$ref": "#/components/schemas/ReportMoney" } } }, "ProfitAndLossClassification": { "type": "object", "required": [ "code", "label", "accounts", "total" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ProfitAndLossAccountRow" } }, "total": { "$ref": "#/components/schemas/ProfitAndLossTotals" } } }, "ProfitAndLossGroup": { "type": "object", "required": [ "code", "label", "statement", "classifications", "total" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "statement": { "type": "string", "const": "profit_and_loss" }, "classifications": { "type": "array", "items": { "$ref": "#/components/schemas/ProfitAndLossClassification" } }, "total": { "$ref": "#/components/schemas/ProfitAndLossTotals" } } }, "ProfitAndLossReport": { "type": "object", "required": [ "report_type", "currency_code", "fiscal_year", "period", "include_zero", "groups", "result" ], "additionalProperties": false, "properties": { "report_type": { "type": "string", "const": "profit_and_loss" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "period": { "$ref": "#/components/schemas/ReportPeriod" }, "include_zero": { "type": "boolean" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/ProfitAndLossGroup" } }, "result": { "$ref": "#/components/schemas/SignedReportResult" }, "broker_reconciliation": { "$ref": "#/components/schemas/BrokerCalculatedReportReconciliation" }, "annual_cost_warnings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "document_public_id", "number", "posting_date", "due" ], "properties": { "code": { "const": "purchase_annual_costs_pending" }, "document_public_id": { "type": "string" }, "number": { "type": "string" }, "posting_date": { "type": "string", "format": "date" }, "due": { "type": "boolean" } } } } } }, "ProfitAndLossReportResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProfitAndLossReport" } } }, "OpeningBalanceLineInput": { "type": "object", "required": [ "ledger_account_public_id", "side", "amount" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "maxLength": 32, "pattern": "^(?=.*[1-9])(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,4})?$" }, "fx": { "$ref": "#/components/schemas/OpeningFxConversionInput" } } }, "PutOpeningBalanceRequest": { "type": "object", "required": [ "expected_revision", "lines", "state_hash" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "lines": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/OpeningBalanceLineInput" }, "description": "Empty clears; a non-empty array requires at least two balanced lines." }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Confirmation hash returned by the opening-balance preview, binding the source and all existing currency-valuation effects." } } }, "OpeningBalanceLine": { "type": "object", "required": [ "line_number", "ledger_account", "side", "amount", "fx" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer", "minimum": 1 }, "ledger_account": { "$ref": "#/components/schemas/OpeningBalanceLedgerAccountReference" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string" }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/OpeningBalanceFxDetail" }, { "type": "null" } ] } } }, "OpeningBalance": { "type": "object", "required": [ "public_id", "currency_code", "fiscal_year", "revision", "line_count", "total_debit", "total_credit", "lines" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string" }, "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "revision": { "type": "integer", "minimum": 1 }, "line_count": { "type": "integer", "minimum": 2, "maximum": 500 }, "total_debit": { "type": "string" }, "total_credit": { "type": "string" }, "lines": { "type": "array", "minItems": 2, "maxItems": 500, "items": { "$ref": "#/components/schemas/OpeningBalanceLine" } } } }, "OpeningBalanceResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OpeningBalance" } } }, "OpeningBalanceCommandResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/OpeningBalance" }, { "type": "null" } ] } } }, "ManualFxConversionInput": { "type": "object", "required": [ "native_currency_code", "native_amount", "conversion_mode" ], "additionalProperties": false, "properties": { "native_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string", "maxLength": 32 }, "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string", "maxLength": 40 }, "converted_base_amount": { "type": "string", "maxLength": 32 }, "purposes": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "enum": [ "transaction", "vat", "settlement", "revaluation", "opening_balance" ] } } } }, "OpeningFxConversionInput": { "type": "object", "required": [ "native_currency_code", "native_amount", "conversion_mode", "effective_date" ], "additionalProperties": false, "properties": { "native_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string", "maxLength": 32 }, "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string", "maxLength": 40 }, "converted_base_amount": { "type": "string", "maxLength": 32 }, "effective_date": { "type": "string", "format": "date" } } }, "FxSettlementEvidence": { "type": "object", "required": [ "position_side", "native_outstanding", "base_carrying_outstanding", "native_settled", "settlement_base_equivalent", "final" ], "additionalProperties": false, "properties": { "position_side": { "type": "string", "enum": [ "debit", "credit" ] }, "native_outstanding": { "type": "string" }, "base_carrying_outstanding": { "type": "string" }, "native_settled": { "type": "string" }, "settlement_base_equivalent": { "type": "string" }, "final": { "type": "boolean" } } }, "LedgerIdentity": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "GeneratedFxResult": { "type": "object", "required": [ "role", "source_ledger_account", "transaction_equivalent", "carrying_released", "result_amount" ], "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "realized_fx_gain", "realized_fx_loss" ] }, "source_ledger_account": { "$ref": "#/components/schemas/LedgerIdentity" }, "transaction_equivalent": { "type": "string" }, "carrying_released": { "type": "string" }, "result_amount": { "type": "string" } } }, "AppliedFxRate": { "type": "object", "required": [ "foreign_currency", "base_currency", "source_foreign_amount", "converted_base_amount", "input_mode", "rate_numerator", "rate_denominator", "convention", "effective_date", "purposes" ], "additionalProperties": false, "properties": { "foreign_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "source_foreign_amount": { "type": "string" }, "converted_base_amount": { "type": "string" }, "input_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate_numerator": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "rate_denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "convention": { "type": "string", "const": "base_per_foreign_unit" }, "effective_date": { "type": "string", "format": "date" }, "purposes": { "type": "array", "items": { "type": "string", "enum": [ "transaction", "vat", "settlement", "revaluation", "opening_balance" ] } } } }, "JournalFxPreviewLine": { "type": "object", "required": [ "line_number", "ledger_account", "side", "amount", "native_currency", "native_amount", "transaction_equivalent", "carrying_release", "generated_fx_result" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer", "minimum": 1 }, "ledger_account": { "$ref": "#/components/schemas/LedgerIdentity" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string" }, "native_currency": { "type": [ "string", "null" ] }, "native_amount": { "type": [ "string", "null" ] }, "transaction_equivalent": { "type": [ "string", "null" ] }, "carrying_release": { "type": [ "string", "null" ] }, "generated_fx_result": { "oneOf": [ { "$ref": "#/components/schemas/GeneratedFxResult" }, { "type": "null" } ] } } }, "FxPosition": { "type": "object", "required": [ "side", "native", "carrying" ], "additionalProperties": false, "properties": { "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "native": { "type": "string" }, "carrying": { "type": "string" } } }, "JournalFxPreview": { "type": "object", "required": [ "posting_date", "currency_code", "state_hash", "carrying_dependent", "lines", "positions_after" ], "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "carrying_dependent": { "type": "boolean" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/JournalFxPreviewLine" } }, "positions_after": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FxPosition" } }, "opening_items": { "type": "array", "items": { "$ref": "#/components/schemas/JournalOpeningItemEffect" } }, "periodic_valuations": { "type": "array", "items": { "$ref": "#/components/schemas/JournalPeriodicValuation" } } } }, "JournalFxPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/JournalFxPreview" } } }, "FxMappingItem": { "type": "object", "required": [ "role", "ledger_account", "revision" ], "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "realized_fx_gain", "realized_fx_loss", "unrealized_fx_gain", "unrealized_fx_loss" ] }, "ledger_account": { "oneOf": [ { "$ref": "#/components/schemas/LedgerIdentity" }, { "type": "null" } ] }, "revision": { "type": [ "integer", "null" ], "minimum": 1 } } }, "FxAccountMappings": { "type": "object", "required": [ "realized_fx_gain", "realized_fx_loss", "unrealized_fx_gain", "unrealized_fx_loss" ], "additionalProperties": false, "properties": { "realized_fx_gain": { "$ref": "#/components/schemas/FxMappingItem" }, "realized_fx_loss": { "$ref": "#/components/schemas/FxMappingItem" }, "unrealized_fx_gain": { "$ref": "#/components/schemas/FxMappingItem" }, "unrealized_fx_loss": { "$ref": "#/components/schemas/FxMappingItem" } } }, "FxAccountMappingsResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FxAccountMappings" } } }, "FxMappingInput": { "type": "object", "required": [ "ledger_account_public_id" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "expected_revision": { "type": [ "integer", "null" ], "minimum": 1 } } }, "PutFxAccountMappingsRequest": { "type": "object", "required": [ "mappings" ], "additionalProperties": false, "properties": { "mappings": { "type": "object", "additionalProperties": false, "properties": { "realized_fx_gain": { "$ref": "#/components/schemas/FxMappingInput" }, "realized_fx_loss": { "$ref": "#/components/schemas/FxMappingInput" }, "unrealized_fx_gain": { "$ref": "#/components/schemas/FxMappingInput" }, "unrealized_fx_loss": { "$ref": "#/components/schemas/FxMappingInput" } } } } }, "FxRateInput": { "type": "object", "required": [ "foreign_currency_code", "rate", "effective_date" ], "additionalProperties": false, "properties": { "foreign_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "rate": { "type": "string", "maxLength": 40 }, "effective_date": { "type": "string", "format": "date" } } }, "FxRevaluationInputBase": { "type": "object", "required": [ "as_of", "rates" ], "properties": { "as_of": { "type": "string", "format": "date" }, "rates": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/FxRateInput" }, "description": "Quotes for the requested date. Under periodic cash valuation saved closing quotes from that exact date are reused; supply missing or explicitly corrected quotes. An empty array is valid when no quote is missing." }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "revaluation" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Legacy cash policy only. A non-empty day_order is explicitly rejected when periodic cash valuation is active." } } }, "PreviewFxRevaluationRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/FxRevaluationInputBase" }, { "type": "object", "properties": { "revaluation_public_id": { "$ref": "#/components/schemas/Ulid" } } } ], "unevaluatedProperties": false }, { "type": "object", "required": [ "operation", "revaluation_public_id" ], "additionalProperties": false, "properties": { "operation": { "type": "string", "const": "remove" }, "revaluation_public_id": { "$ref": "#/components/schemas/Ulid" } }, "description": "Periodic-policy removal preview. It includes the original journal to remove and any required neutralisation or later valuation additions; ordinary future sources are unchanged." } ] }, "PostFxRevaluationRequest": { "allOf": [ { "$ref": "#/components/schemas/FxRevaluationInputBase" }, { "type": "object", "required": [ "position_state_hash", "rate_set_hash" ], "properties": { "position_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "rate_set_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "dependency_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Complete authorized preview proof. Always required under periodic cash valuation, including an unchanged correction; under the legacy policy required for retained dependent changes. Must match the freshly rebuilt plan." } } } ], "unevaluatedProperties": false }, "UpdateFxRevaluationRequest": { "allOf": [ { "$ref": "#/components/schemas/PostFxRevaluationRequest" }, { "type": "object", "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } ], "unevaluatedProperties": false }, "DeleteFxRevaluationRequest": { "type": "object", "required": [ "expected_revision" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "dependency_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Required under periodic cash valuation. Obtain it from the operation=remove preview for this target and revision. Legacy policy retains its existing direct removal contract." } } }, "FxRateSnapshot": { "type": "object", "required": [ "foreign_currency", "base_currency", "rate_numerator", "rate_denominator", "convention", "effective_date", "formula_version" ], "additionalProperties": false, "properties": { "foreign_currency": { "type": "string" }, "base_currency": { "type": "string" }, "rate_numerator": { "type": "string" }, "rate_denominator": { "type": "string" }, "convention": { "type": "string", "const": "base_per_foreign_unit" }, "effective_date": { "type": "string", "format": "date" }, "formula_version": { "type": "integer", "const": 1 } } }, "FxRevaluationPreviewRate": { "allOf": [ { "$ref": "#/components/schemas/FxRateSnapshot" }, { "type": "object", "required": [ "rate" ], "properties": { "rate": { "type": "string" } } } ], "unevaluatedProperties": false }, "FxRevaluationPreviewLine": { "type": "object", "required": [ "line_number", "ledger_account", "currency_code", "native_side", "native_amount", "base_carrying_side", "base_carrying_amount", "effective_carrying_rate", "proposed_rate", "remeasured_side", "remeasured_amount", "difference_amount", "difference_direction", "result_kind", "result_role", "result_ledger_account", "position_present" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer" }, "ledger_account": { "$ref": "#/components/schemas/LedgerIdentity" }, "currency_code": { "type": "string" }, "native_side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "native_amount": { "type": "string" }, "base_carrying_side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "base_carrying_amount": { "type": "string" }, "effective_carrying_rate": { "type": [ "string", "null" ] }, "proposed_rate": { "type": "string" }, "remeasured_side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "remeasured_amount": { "type": "string" }, "difference_amount": { "type": "string" }, "difference_direction": { "type": "string", "enum": [ "increase", "decrease", "zero" ] }, "result_kind": { "type": "string", "enum": [ "gain", "loss", "zero" ] }, "result_role": { "type": [ "string", "null" ], "enum": [ "unrealized_fx_gain", "unrealized_fx_loss", null ] }, "result_ledger_account": { "oneOf": [ { "$ref": "#/components/schemas/LedgerIdentity" }, { "type": "null" } ] }, "position_present": { "type": "boolean", "description": "False only for a previously measured position removed by an earlier source correction; its rates and control remain." } } }, "FxRevaluationPreview": { "type": "object", "required": [ "as_of", "position_state_hash", "rate_set_hash", "rates", "lines", "warnings" ], "additionalProperties": false, "properties": { "as_of": { "type": "string", "format": "date" }, "position_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "rate_set_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/FxRevaluationPreviewRate" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FxRevaluationPreviewLine" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "dependency_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "dependent_changes": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeDependentJournal" } }, "position_hash_version": { "type": "integer", "enum": [ 2, 3 ] }, "periodic": { "$ref": "#/components/schemas/PeriodicValuationPreview" } } }, "FxRevaluationPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FxRevaluationPreview" } } }, "FxRevaluationResultLine": { "type": "object", "required": [ "line_number", "ledger_account", "native_side", "native_currency", "native_amount", "base_carrying_side", "base_carrying_amount", "remeasured_side", "remeasured_amount", "difference_amount", "result_kind", "result_role", "result_ledger_account", "position_present" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer" }, "ledger_account": { "$ref": "#/components/schemas/LedgerIdentity" }, "native_side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "native_currency": { "type": "string" }, "native_amount": { "type": "string" }, "base_carrying_side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "base_carrying_amount": { "type": "string" }, "remeasured_side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] }, "remeasured_amount": { "type": "string" }, "difference_amount": { "type": "string" }, "result_kind": { "type": "string", "enum": [ "gain", "loss", "zero" ] }, "result_role": { "type": [ "string", "null" ] }, "result_ledger_account": { "oneOf": [ { "$ref": "#/components/schemas/LedgerIdentity" }, { "type": "null" } ] }, "position_present": { "type": "boolean", "description": "False only for a previously measured position removed by an earlier source correction; its rates and control remain." } } }, "FxRevaluation": { "type": "object", "required": [ "public_id", "status", "journal_entry", "fiscal_year", "as_of", "revision", "position_state_hash", "rate_set_hash", "supersedes_revaluation_public_id", "rates", "lines", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "enum": [ "posted", "no_difference", "deleted" ] }, "journal_entry": { "oneOf": [ { "type": "object", "required": [ "public_id", "number" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" } } }, { "type": "null" } ] }, "fiscal_year": { "oneOf": [ { "$ref": "#/components/schemas/JournalEntryFiscalYear" }, { "type": "null" } ] }, "as_of": { "type": [ "string", "null" ], "format": "date" }, "revision": { "type": "integer", "minimum": 1 }, "position_state_hash": { "type": [ "string", "null" ] }, "rate_set_hash": { "type": [ "string", "null" ] }, "supersedes_revaluation_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/FxRateSnapshot" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FxRevaluationResultLine" } }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "position_hash_version": { "type": "integer", "const": 3 }, "periodic_policy": { "type": "boolean", "const": true, "description": "Current administration uses the periodic command workflow, including for a retained historical valuation." }, "periodic": { "type": "object", "required": [ "positions" ], "additionalProperties": false, "properties": { "positions": { "type": "array", "items": { "$ref": "#/components/schemas/PeriodicValuationPosition" } } } } } }, "FxRevaluationResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FxRevaluation" } } }, "FxRevaluationCollection": { "type": "object", "required": [ "data", "links", "meta" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FxRevaluation" } }, "links": { "$ref": "#/components/schemas/CursorLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } } }, "OpeningBalanceLedgerAccountReference": { "type": "object", "required": [ "public_id", "code", "name", "normal_balance", "status" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } }, "OpeningBalanceFxDetail": { "type": "object", "required": [ "foreign_currency", "native_amount", "base_currency", "base_carrying_amount", "input_mode", "rate_numerator", "rate_denominator", "effective_date", "purpose" ], "additionalProperties": false, "properties": { "foreign_currency": { "type": "string" }, "native_amount": { "type": "string" }, "base_currency": { "type": "string" }, "base_carrying_amount": { "type": "string" }, "input_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate_numerator": { "type": "string" }, "rate_denominator": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "purpose": { "type": "string", "const": "opening_balance" } } }, "NativeMutation": { "type": "object", "required": [ "amount", "side", "affects_native_balance" ], "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "affects_native_balance": { "type": "boolean" } } }, "CompactFxRate": { "type": "object", "required": [ "numerator", "denominator", "convention", "effective_date" ], "additionalProperties": false, "properties": { "numerator": { "type": "string" }, "denominator": { "type": "string" }, "convention": { "type": "string", "const": "base_per_foreign_unit" }, "effective_date": { "type": "string", "format": "date" } } }, "SalesFxInput": { "type": "object", "required": [ "conversion_mode" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": [ "string", "null" ], "maxLength": 40 }, "converted_base_amount": { "type": [ "string", "null" ], "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } }, "oneOf": [ { "required": [ "rate" ], "properties": { "conversion_mode": { "const": "rate" } }, "not": { "required": [ "converted_base_amount" ] } }, { "required": [ "converted_base_amount" ], "properties": { "conversion_mode": { "const": "converted_amount" } }, "not": { "required": [ "rate" ] } } ] }, "SalesViesInput": { "type": "object", "required": [ "source" ], "additionalProperties": false, "properties": { "source": { "type": "string", "enum": [ "official", "manual_evidence" ] }, "evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 } } }, "SalesRouteBaseAmountInput": { "type": "object", "required": [ "administration_public_id", "base_amount" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "base_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } } }, "SalesRouteEdgeAmountInput": { "type": "object", "required": [ "configuration_public_id", "native_amount" ], "additionalProperties": false, "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteBaseAmountInput" } } } }, "SalesRouteEdgeAmountPreview": { "type": "object", "required": [ "configuration_public_id", "denomination_currency_code", "native_amount", "base_amounts" ], "additionalProperties": false, "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" }, "base_amounts": { "type": "array", "items": { "$ref": "#/components/schemas/SalesRouteBaseAmountInput" } } } }, "SalesDirectSettlementInput": { "type": "object", "required": [ "channel", "amount", "settlement_date" ], "additionalProperties": false, "properties": { "full_amount": { "type": "boolean", "description": "Explicit full receipt, never a write-off. Same-currency amount must equal the document total. For a base-currency document and foreign receipt the full base value determines the receipt rate; omit receipt_fx. A direct_sale or external_invoice first recorded together with its full receipt on the same date in the same foreign currency shares the document FX input when receipt_fx is omitted. An explicit receipt_fx always takes precedence and records the separate receipt valuation. Different dates or foreign currencies and later receipts require their own applicable conversion; neither source is subsequently revalued by changing the other. UI-only choices are not API fields." }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "settlement_date": { "type": "string", "format": "date", "examples": [ "2026-08-25" ] }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Amount actually received, using canonical point notation.", "examples": [ "274.00" ] }, "document_currency_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Amount allocated to the Sales document in document currency; this may leave an explicit remainder open.", "examples": [ "274.00" ] }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "difference_treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ], "description": "Explicit handling of a difference. No treatment is selected automatically.", "examples": [ "leave_open" ] }, "document_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "rc_contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Explicit RC counterparty, independent of the sales customer. Must be reachable through configured RC links in the authorized administrations. No name or email matching." } }, "allOf": [ { "if": { "properties": { "channel": { "const": "rekening_courant" } }, "required": [ "channel" ] }, "then": { "required": [ "rc_contact_public_id" ], "properties": { "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "else": { "properties": { "rc_contact_public_id": { "type": "null" } } } } ] }, "SalesDocumentLineInput": { "type": "object", "required": [ "amount" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "no_vat_reason": { "type": [ "string", "null" ], "enum": [ "receipt_without_consideration", null ] }, "posting_purpose": { "type": "string", "enum": [ "revenue", "balance_settlement" ], "description": "Omitted means the established revenue meaning. Balance settlement is explicit and supported only for existing external invoices and credits." }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } }, "oneOf": [ { "required": [ "vat_treatment_code", "amount_mode" ], "not": { "required": [ "no_vat_reason" ], "properties": { "no_vat_reason": { "const": "receipt_without_consideration" } } } }, { "required": [ "no_vat_reason" ], "properties": { "no_vat_reason": { "const": "receipt_without_consideration" }, "margin_method": { "const": "none" } }, "not": { "required": [ "vat_treatment_code" ] } } ], "description": "Choose a VAT treatment, or explicitly choose receipt_without_consideration for a direct receipt (or an internal return of that original receipt). No automatic tax default. With the explicit reason the amount is used as entered; amount_mode has no VAT effect.", "allOf": [ { "if": { "required": [ "posting_purpose" ], "properties": { "posting_purpose": { "const": "balance_settlement" } } }, "then": { "required": [ "balance_ledger_account_public_id" ], "not": { "required": [ "revenue_ledger_account_public_id" ] } }, "else": { "not": { "required": [ "balance_ledger_account_public_id" ] }, "required": [ "revenue_ledger_account_public_id" ] } } ] }, "SalesCreditLineInput": { "type": "object", "required": [ "amount" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "original_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "original_opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "original_opening_vat_part_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_purpose": { "type": "string", "enum": [ "revenue", "balance_settlement" ], "description": "Omitted means the established revenue meaning. Balance settlement is explicit and supported only for existing external invoices and credits." }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } }, "anyOf": [ { "required": [ "original_line_public_id" ], "properties": { "original_line_public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "required": [ "original_line_number" ], "properties": { "original_line_number": { "type": "integer", "minimum": 1, "maximum": 100 } } }, { "required": [ "original_opening_vat_part_public_id" ], "properties": { "original_opening_vat_part_public_id": { "$ref": "#/components/schemas/Ulid" } } } ], "allOf": [ { "if": { "required": [ "posting_purpose" ], "properties": { "posting_purpose": { "const": "balance_settlement" } } }, "then": { "required": [ "balance_ledger_account_public_id" ], "not": { "required": [ "revenue_ledger_account_public_id" ] } }, "else": { "not": { "required": [ "balance_ledger_account_public_id" ] } } } ] }, "SalesPublicVatContext": { "type": "object", "required": [ "region", "supply_type", "customer_type" ], "additionalProperties": false, "properties": { "region": { "type": "string", "enum": [ "nl", "eu", "non_eu" ] }, "supply_type": { "type": "string", "enum": [ "goods", "services", "digital_services" ] }, "customer_type": { "type": "string", "enum": [ "b2b", "b2c" ] } } }, "SalesPublicRate": { "type": "object", "required": [ "numerator", "denominator" ], "additionalProperties": false, "properties": { "numerator": { "type": "string", "pattern": "^\\d+$" }, "denominator": { "type": "string", "pattern": "^[1-9]\\d*$" } } }, "SalesPublicEuB2c": { "type": "object", "required": [ "status", "vat_country", "reporting_route", "category", "rate", "decision" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "accepted" ] }, "vat_country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "reporting_route": { "type": "string", "enum": [ "ordinary_nl", "oss", "foreign_return" ] }, "category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ] }, "rate": { "oneOf": [ { "type": "object", "required": [ "numerator", "denominator", "effective_date", "valid_from", "valid_until", "official_source", "source_version", "revision" ], "additionalProperties": false, "properties": { "numerator": { "type": "string", "pattern": "^\\d+$" }, "denominator": { "type": "string", "pattern": "^[1-9]\\d*$" }, "effective_date": { "type": "string", "format": "date" }, "valid_from": { "type": "string", "format": "date" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "official_source": { "type": "string", "format": "uri" }, "source_version": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 } } }, { "type": "null" } ] }, "decision": { "type": "object", "required": [ "destination_vat_applies", "destination_country", "threshold", "policy" ], "additionalProperties": false, "properties": { "destination_vat_applies": { "type": "boolean" }, "destination_country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "threshold": { "description": "Current decisions use the explicitly configured inclusive day. The former turnover shape is retained only for already stored historical snapshots and their source-bound credits.", "oneOf": [ { "type": "object", "required": [ "amount_eur", "required_from", "basis" ], "additionalProperties": false, "properties": { "amount_eur": { "type": "string", "const": "10000.0000" }, "required_from": { "type": [ "string", "null" ], "format": "date" }, "basis": { "type": "string", "const": "configured_day" } } }, { "type": "object", "required": [ "amount_eur", "prior_year_turnover", "current_year_before", "prospective_sale", "current_year_after", "crossed_before_sale", "crossed_by_sale" ], "additionalProperties": false, "properties": { "amount_eur": { "type": "string" }, "prior_year_turnover": { "type": "string" }, "current_year_before": { "type": "string" }, "prospective_sale": { "type": "string" }, "current_year_after": { "type": "string" }, "crossed_before_sale": { "type": "boolean" }, "crossed_by_sale": { "type": "boolean" } } } ] }, "policy": { "type": "object", "required": [ "public_id", "revision", "valid_from", "decision_reason", "destination_vat_elected" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "valid_from": { "type": "string", "format": "date" }, "decision_reason": { "type": "string" }, "destination_vat_elected": { "type": "boolean" } } } }, "description": "Stored actual treatment and policy expectation. New expectation/choice fields are absent in older historical snapshots; absence is unknown and is not recalculated." }, "configured_destination_vat_applies": { "type": "boolean" }, "choice_differs_from_settings": { "type": "boolean" }, "transition_day": { "type": "boolean" }, "reporting_route_origin": { "type": "string", "enum": [ "explicit_local" ] }, "registration_evidence_status": { "type": "string", "enum": [ "recorded", "not_recorded" ], "description": "Evidence recorded in this administration at the time of this explicit local entry, not legal registration or filing status." } } }, "SalesPublicTraceMetadata": { "type": "object", "additionalProperties": false, "properties": { "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_positive": { "type": "boolean" }, "margin_inclusive": { "type": "string" }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] } } }, "SalesPublicProfileContext": { "type": "object", "required": [ "vat_regime", "tax_point_system", "invoice_rounding_method", "article_23_permit", "profile_valid_from", "profile_revision" ], "additionalProperties": false, "properties": { "vat_regime": { "type": "string" }, "tax_point_system": { "type": "string", "enum": [ "invoice", "cash" ] }, "invoice_rounding_method": { "type": "string" }, "article_23_permit": { "type": "boolean" }, "profile_valid_from": { "type": "string", "format": "date" }, "profile_revision": { "type": "integer", "minimum": 1 } } }, "SalesPublicCalculationTrace": { "type": "object", "required": [ "treatment_code", "treatment_version", "formula_version", "strategy", "rate", "unrounded_vat", "rounded_vat", "rounding_method", "metadata", "vat_date", "correction_vat_date", "vat_date_derivation", "relevant_source_dates", "profile_context" ], "additionalProperties": false, "properties": { "treatment_code": { "type": [ "string", "null" ] }, "treatment_version": { "type": [ "integer", "null" ], "minimum": 1 }, "formula_version": { "type": "integer", "minimum": 1 }, "strategy": { "type": "string" }, "rate": { "oneOf": [ { "$ref": "#/components/schemas/SalesPublicRate" }, { "type": "null" } ] }, "unrounded_vat": { "type": [ "string", "null" ] }, "rounded_vat": { "type": "string" }, "rounding_method": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/SalesPublicTraceMetadata" }, "vat_date": { "type": [ "string", "null" ], "format": "date" }, "correction_vat_date": { "type": [ "string", "null" ], "format": "date" }, "vat_date_derivation": { "type": [ "string", "null" ] }, "relevant_source_dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "profile_context": { "oneOf": [ { "$ref": "#/components/schemas/SalesPublicProfileContext" }, { "type": "null" } ] }, "no_vat_reason": { "type": [ "string", "null" ], "enum": [ "receipt_without_consideration", null ] }, "fiscal_source": { "$ref": "#/components/schemas/SalesOpeningFiscalContext" } }, "allOf": [ { "if": { "required": [ "profile_context" ], "properties": { "profile_context": { "type": "null" } } }, "then": { "required": [ "fiscal_source" ] } } ] }, "SalesPublicLedgerEffect": { "type": "object", "required": [ "role", "side", "amount" ], "additionalProperties": false, "properties": { "role": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string" } } }, "SalesPublicReportingEffect": { "type": "object", "required": [ "scheme", "code", "component", "route_condition", "amount", "base_amount", "polarity" ], "additionalProperties": false, "properties": { "scheme": { "type": "string" }, "code": { "type": "string" }, "component": { "type": "string" }, "route_condition": { "type": "string" }, "amount": { "type": "string" }, "base_amount": { "type": "string" }, "polarity": { "type": "string" } } }, "SalesCashCreditSplit": { "type": "object", "required": [ "native_deferred_vat_reversal", "native_recognized_vat_reversal", "base_deferred_vat_reversal", "base_recognized_vat_reversal", "native_deferred_taxable_reversal", "native_recognized_taxable_reversal", "base_deferred_taxable_reversal", "base_recognized_taxable_reversal", "native_rounding_residue", "base_rounding_residue" ], "additionalProperties": false, "properties": { "native_deferred_vat_reversal": { "type": "string" }, "native_recognized_vat_reversal": { "type": "string" }, "base_deferred_vat_reversal": { "type": "string" }, "base_recognized_vat_reversal": { "type": "string" }, "native_deferred_taxable_reversal": { "type": "string" }, "native_recognized_taxable_reversal": { "type": "string" }, "base_deferred_taxable_reversal": { "type": "string" }, "base_recognized_taxable_reversal": { "type": "string" }, "native_rounding_residue": { "type": "string" }, "base_rounding_residue": { "type": "string" } } }, "SalesPublicVatFact": { "type": "object", "required": [ "treatment_code", "profile_revision", "vat_context", "eu_b2c", "cash_credit_split", "deferred", "deferred_reason", "ledger_effects", "reporting_effects_when_recognized" ], "additionalProperties": false, "properties": { "treatment_code": { "type": [ "string", "null" ] }, "profile_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "vat_context": { "oneOf": [ { "$ref": "#/components/schemas/SalesVatContextInput" }, { "type": "object", "maxProperties": 0 } ] }, "eu_b2c": { "oneOf": [ { "$ref": "#/components/schemas/SalesPublicEuB2c" }, { "type": "null" } ] }, "cash_credit_split": { "oneOf": [ { "$ref": "#/components/schemas/SalesCashCreditSplit" }, { "type": "null" } ] }, "deferred": { "type": "boolean" }, "deferred_reason": { "type": [ "string", "null" ] }, "ledger_effects": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPublicLedgerEffect" } }, "reporting_effects_when_recognized": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPublicReportingEffect" } }, "no_vat_reason": { "type": [ "string", "null" ], "enum": [ "receipt_without_consideration", null ] }, "fiscal_source": { "$ref": "#/components/schemas/SalesOpeningFiscalContext" } } }, "SalesLineVatProfile": { "type": "object", "required": [ "tax_point_system", "vat_regime", "rounding_method", "valid_from", "revision" ], "additionalProperties": false, "properties": { "tax_point_system": { "type": "string", "enum": [ "invoice", "cash" ] }, "vat_regime": { "type": "string" }, "rounding_method": { "type": "string" }, "valid_from": { "type": "string", "format": "date" }, "revision": { "type": "integer", "minimum": 1 } } }, "SalesDocumentInput": { "type": "object", "required": [ "document_type", "invoice_date", "supply_date", "lines" ], "additionalProperties": false, "properties": { "document_type": { "type": "string", "enum": [ "external_invoice", "direct_sale", "external_credit_note" ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vat_context": { "oneOf": [ { "$ref": "#/components/schemas/SalesVatContextInput" }, { "type": "object", "maxProperties": 0 } ], "description": "Required for VAT-treated lines; omit for a receipt without consideration." }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesInput" }, { "type": "null" } ] }, "vies_proof": { "type": [ "string", "null" ], "maxLength": 4096 }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "$ref": "#/components/schemas/SalesDocumentLineInput" }, { "$ref": "#/components/schemas/SalesCreditLineInput" } ] } }, "direct_settlement": { "oneOf": [ { "$ref": "#/components/schemas/SalesDirectSettlementInput" }, { "type": "null" } ] }, "original_document_public_ids": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" }, "description": "Internal credit sources, all in the same administration, customer and currency. Every credit line identifies one source." }, "original_opening_item_public_id": { "$ref": "#/components/schemas/Ulid" } }, "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "external_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/SalesCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] }, { "required": [ "original_opening_item_public_id" ] }, { "properties": { "lines": { "contains": { "required": [ "original_opening_item_public_id" ], "properties": { "original_opening_item_public_id": { "$ref": "#/components/schemas/Ulid" } } } } }, "required": [ "lines" ] } ] } ] }, "else": { "required": [ "currency_code" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/SalesDocumentLineInput" } } } } } ] }, "SalesVatContextInput": { "type": "object", "required": [ "region", "supply_type", "customer_type" ], "additionalProperties": false, "properties": { "region": { "type": "string", "enum": [ "nl", "eu", "non_eu" ] }, "supply_type": { "type": "string", "enum": [ "goods", "services", "digital_services" ] }, "customer_type": { "type": "string", "enum": [ "b2b", "b2c" ] } } }, "PostSalesDocumentRequest": { "type": "object", "required": [ "document_type", "invoice_date", "supply_date", "lines", "state_hash" ], "additionalProperties": false, "properties": { "document_type": { "type": "string", "enum": [ "external_invoice", "direct_sale", "external_credit_note" ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vat_context": { "oneOf": [ { "$ref": "#/components/schemas/SalesVatContextInput" }, { "type": "object", "maxProperties": 0 } ], "description": "Required for VAT-treated lines; omit for a receipt without consideration." }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesInput" }, { "type": "null" } ] }, "vies_proof": { "type": [ "string", "null" ], "maxLength": 4096 }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "$ref": "#/components/schemas/SalesDocumentLineInput" }, { "$ref": "#/components/schemas/SalesCreditLineInput" } ] } }, "direct_settlement": { "oneOf": [ { "$ref": "#/components/schemas/SalesDirectSettlementInput" }, { "type": "null" } ] }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "original_document_public_ids": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" }, "description": "Internal credit sources, all in the same administration, customer and currency. Every credit line identifies one source." } }, "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "external_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/SalesCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "else": { "required": [ "currency_code" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/SalesDocumentLineInput" } } } } } ] }, "UpdateSalesDocumentRequest": { "type": "object", "required": [ "document_type", "invoice_date", "supply_date", "lines", "state_hash", "expected_revision" ], "additionalProperties": false, "properties": { "document_type": { "type": "string", "enum": [ "external_invoice", "direct_sale", "external_credit_note", "issued_invoice", "issued_credit_note" ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vat_context": { "oneOf": [ { "$ref": "#/components/schemas/SalesVatContextInput" }, { "type": "object", "maxProperties": 0 } ], "description": "Required for VAT-treated lines; omit for a receipt without consideration." }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesInput" }, { "type": "null" } ] }, "vies_proof": { "type": [ "string", "null" ], "maxLength": 4096 }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "$ref": "#/components/schemas/UpdateSalesDocumentLineInput" }, { "$ref": "#/components/schemas/UpdateSalesCreditLineInput" }, { "$ref": "#/components/schemas/UpdateIssuedInvoiceLineInput" }, { "$ref": "#/components/schemas/UpdateIssuedCreditLineInput" } ] } }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 }, "asset_disposals": { "$ref": "#/components/schemas/FixedAssetSaleChoices" }, "original_document_public_ids": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" }, "description": "Internal credit sources, all in the same administration, customer and currency. Every credit line identifies one source." }, "historical_origin_changes": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOriginChange" }, "maxItems": 100, "description": "Explicitly keep, replace amounts or remove historical capacity reservations in the same financial correction preview. Unchanged reservations remain subject to both source and credit capacity checks." } }, "allOf": [ { "if": { "required": [ "document_type" ], "properties": { "document_type": { "enum": [ "issued_invoice", "issued_credit_note" ] } } }, "then": { "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "issued_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateIssuedCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "else": { "required": [ "currency_code", "contact_public_id" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateIssuedInvoiceLineInput" } } } } } ] }, "else": { "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "external_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateSalesCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "else": { "required": [ "currency_code" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateSalesDocumentLineInput" } } } } } ] } } ] }, "SalesCreditNoteInput": { "type": "object", "required": [ "invoice_date", "supply_date", "lines" ], "additionalProperties": false, "properties": { "external_number": { "type": "string", "minLength": 1, "maxLength": 80 }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/SalesCreditLineInput" } } }, "description": "Source-linked credit note or return. An invoice source requires the credit-note number; a direct-sale return has no external number. Source account, VAT and FX facts are inherited." }, "PostSalesCreditNoteRequest": { "type": "object", "required": [ "invoice_date", "supply_date", "lines", "state_hash" ], "additionalProperties": false, "properties": { "external_number": { "type": "string", "minLength": 1, "maxLength": 80 }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/SalesCreditLineInput" } }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "description": "Source-linked credit note or return. An invoice source requires the credit-note number; a direct-sale return has no external number. Source account, VAT and FX facts are inherited." }, "SalesSettlementInput": { "type": "object", "required": [ "channel", "settlement_date", "amount" ], "additionalProperties": false, "properties": { "full_amount": { "type": "boolean", "description": "Explicit full receipt of the remaining document amount, without a payment-difference treatment. Same-currency amount must match outstanding. For a base-currency document with foreign receipt, omit receipt_fx: its base value is the outstanding document amount. Other foreign receipts retain their actual payment valuation." }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_currency_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "difference_treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ] }, "rc_contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Explicit RC counterparty, independent of the sales customer. Must be reachable through configured RC links in the authorized administrations. No name or email matching." }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." } }, "allOf": [ { "if": { "properties": { "channel": { "const": "rekening_courant" } }, "required": [ "channel" ] }, "then": { "required": [ "rc_contact_public_id" ], "properties": { "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "else": { "properties": { "rc_contact_public_id": { "type": "null" } } } } ] }, "PostSalesSettlementRequest": { "type": "object", "required": [ "channel", "settlement_date", "amount", "state_hash" ], "additionalProperties": false, "properties": { "full_amount": { "$ref": "#/components/schemas/SalesSettlementInput/properties/full_amount" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_currency_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "difference_treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ] }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." } } }, "SalesCustomerCreditRefundInput": { "type": "object", "required": [ "channel", "settlement_date", "amount" ], "additionalProperties": false, "properties": { "customer_credit_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "customer_credit_currency_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "rc_contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Explicit RC counterparty, independent of the sales customer. Must be reachable through configured RC links in the authorized administrations. No name or email matching." }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." } }, "allOf": [ { "if": { "properties": { "channel": { "const": "rekening_courant" } }, "required": [ "channel" ] }, "then": { "required": [ "rc_contact_public_id" ], "properties": { "rc_contact_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "else": { "properties": { "rc_contact_public_id": { "type": "null" } } } } ] }, "PostSalesCustomerCreditRefundRequest": { "type": "object", "required": [ "channel", "settlement_date", "amount", "state_hash" ], "additionalProperties": false, "properties": { "customer_credit_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "customer_credit_currency_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." } } }, "UpdateSalesCustomerCreditRefundPreviewRequest": { "type": "object", "required": [ "channel", "settlement_date", "amount", "expected_revision" ], "additionalProperties": false, "properties": { "customer_credit_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "customer_credit_currency_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "UpdateSalesCustomerCreditRefundRequest": { "type": "object", "required": [ "channel", "settlement_date", "amount", "state_hash", "expected_revision" ], "additionalProperties": false, "properties": { "customer_credit_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "customer_credit_currency_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "SalesSettlementUpdatePreviewCommand": { "oneOf": [ { "$ref": "#/components/schemas/UpdateSalesSettlementPreviewRequest" }, { "$ref": "#/components/schemas/UpdateSalesCustomerCreditRefundPreviewRequest" } ] }, "SalesSettlementUpdateCommand": { "oneOf": [ { "$ref": "#/components/schemas/UpdateSalesSettlementRequest" }, { "$ref": "#/components/schemas/UpdateSalesCustomerCreditRefundRequest" } ] }, "UpdateSalesSettlementPreviewRequest": { "type": "object", "required": [ "channel", "settlement_date", "amount", "expected_revision" ], "additionalProperties": false, "properties": { "full_amount": { "$ref": "#/components/schemas/SalesSettlementInput/properties/full_amount" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_currency_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "difference_treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ] }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "UpdateSalesSettlementRequest": { "type": "object", "required": [ "channel", "settlement_date", "amount", "state_hash", "expected_revision" ], "additionalProperties": false, "properties": { "full_amount": { "$ref": "#/components/schemas/SalesSettlementInput/properties/full_amount" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountInput" } }, "settlement_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_currency_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "difference_treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ] }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "FixedAssetSaleChoices": { "type": "array", "maxItems": 500, "description": "Explicit choices require fixed_assets:write in addition to sales:write, for preview and confirmation. Omit or send [] for automatic source-derived effects. Asset identities must be distinct.", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "asset_public_id", "action" ], "properties": { "asset_public_id": { "$ref": "#/components/schemas/Ulid" }, "action": { "const": "undo_sale" } } }, { "type": "object", "additionalProperties": false, "required": [ "asset_public_id", "action", "sales_document_public_id", "sales_line_public_id" ], "properties": { "asset_public_id": { "$ref": "#/components/schemas/Ulid" }, "action": { "const": "relink" }, "sales_document_public_id": { "$ref": "#/components/schemas/Ulid" }, "sales_line_public_id": { "$ref": "#/components/schemas/Ulid" } } } ] } }, "FixedAssetBuildingFacts": { "type": "object", "additionalProperties": false, "required": [ "uses", "woz" ], "properties": { "uses": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "effective_on", "use" ], "properties": { "effective_on": { "type": "string", "format": "date" }, "use": { "enum": [ "own_use", "investment" ] } } }, "maxItems": 500, "minItems": 1 }, "woz": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "year", "value" ], "properties": { "year": { "type": "integer", "minimum": 1900, "maximum": 9999 }, "value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "maxItems": 500, "minItems": 0, "description": "Explicitly provide an empty list when future WOZ values are not known. Future registration may be saved, but currently due depreciation requiring a missing floor is rejected; forecasts mark the missing period, without inventing values." }, "transition": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [], "properties": { "prior_depreciation": { "type": [ "boolean", "null" ] }, "depreciation_started_on": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "ends_on": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, "FixedAssetDisposalInput": { "type": "object", "additionalProperties": false, "required": [ "type", "disposed_on", "result_account_public_id" ], "properties": { "type": { "enum": [ "sale", "write_off" ] }, "disposed_on": { "type": "string", "format": "date" }, "result_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "sales_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "sales_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } }, "allOf": [ { "if": { "properties": { "type": { "const": "sale" } } }, "then": { "required": [ "sales_document_public_id", "sales_line_public_id" ], "properties": { "sales_document_public_id": { "$ref": "#/components/schemas/Ulid" }, "sales_line_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "else": { "properties": { "sales_document_public_id": { "type": "null" }, "sales_line_public_id": { "type": "null" } } } } ] }, "FixedAssetAllocationInput": { "type": "object", "additionalProperties": false, "required": [ "document_public_id", "line_public_id", "effective_on", "amount" ], "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "effective_on": { "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "FixedAssetChangeInput": { "type": "object", "additionalProperties": false, "required": [ "effective_on" ], "properties": { "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "effective_on": { "type": "string", "format": "date" }, "residual_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "land_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "remaining_months": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "reason": { "type": [ "string", "null" ], "maxLength": 255 }, "expected_end_on": { "type": [ "string", "null" ], "format": "date", "description": "Inclusive last expected day of useful life. Alternative to remaining_months, not a disposal date. Tax ceilings and building floors still apply." } }, "allOf": [ { "not": { "required": [ "remaining_months", "expected_end_on" ], "properties": { "remaining_months": { "type": "integer" }, "expected_end_on": { "type": "string" } } } } ], "description": "Optional estimate changes from effective_on. Omit both life fields to keep the existing estimate. An explicit month or date switches the life mode; an end date must be on or after both effective_on and in_use_on." }, "FixedAssetCreatePreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "kind", "source_type", "acquired_on", "in_use_on", "starts_on", "residual_value", "acquisition_account_public_id", "accumulated_account_public_id", "expense_account_public_id" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "enum": [ "equipment", "machinery", "vehicle", "building", "land", "goodwill" ] }, "source_type": { "enum": [ "opening", "purchase" ] }, "acquired_on": { "type": "string", "format": "date" }, "in_use_on": { "type": "string", "format": "date" }, "starts_on": { "type": "string", "format": "date" }, "opening_cost": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_accumulated": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_adjustment": { "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_tax_depreciation": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "residual_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "land_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "remaining_months": { "type": [ "integer", "null" ], "minimum": 0 }, "acquisition_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "accumulated_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetAllocationInput" }, "maxItems": 500 }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetChangeInput" }, "maxItems": 500 }, "building_facts": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetBuildingFacts" }, { "type": "null" } ] }, "disposal": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetDisposalInput" }, { "type": "null" } ], "description": "Omission during update preserves the existing disposal; explicit null undoes it, subject to the current preview and open-year checks." }, "asset_vat_allocations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "maxItems": 500, "description": "Explicit cost shares for prior VAT revisions. Null asset_public_id denotes the asset being created/edited. Fully capitalized lines require a closing split." }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expected_end_on": { "type": [ "string", "null" ], "format": "date", "description": "Inclusive last expected day of useful life. Alternative to remaining_months, not a disposal date. Tax ceilings and building floors still apply." } }, "allOf": [ { "if": { "properties": { "source_type": { "const": "opening" } } }, "then": { "required": [ "opening_cost", "opening_accumulated", "opening_adjustment" ], "properties": { "opening_cost": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_accumulated": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_adjustment": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "allocations": { "maxItems": 0 } } }, "else": { "required": [ "allocations" ], "properties": { "opening_cost": { "type": "null" }, "opening_accumulated": { "type": "null" }, "opening_adjustment": { "type": "null" }, "opening_tax_depreciation": { "type": "null" } } } }, { "if": { "properties": { "kind": { "const": "building" } } }, "then": { "required": [ "land_value" ], "properties": { "land_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, { "if": { "properties": { "kind": { "not": { "const": "land" } } } }, "then": { "oneOf": [ { "required": [ "remaining_months" ], "properties": { "remaining_months": { "type": "integer", "minimum": 1 }, "expected_end_on": { "type": "null" } } }, { "required": [ "expected_end_on" ], "properties": { "expected_end_on": { "type": "string", "format": "date" }, "remaining_months": { "type": "null" } } } ] }, "else": { "properties": { "expected_end_on": { "type": "null" }, "remaining_months": { "type": [ "integer", "null" ], "enum": [ 0, null ] } } } }, { "if": { "properties": { "source_type": { "const": "purchase" } } }, "then": { "properties": { "allocations": { "minItems": 1 } } } } ], "description": "Full editable input, not a patch. Monetary values use base-currency decimal strings with up to four places. Source capacity, tax evidence and all affected assets are rechecked together. Clients cannot post free cost_delta changes. For depreciable assets supply exactly one positive remaining_months or expected_end_on. Dates must be on or after the later of starts_on and in_use_on. Months retain their existing calculation; end dates use the exact calendar-month/day fraction. No current-fiscal-year fallback is applied." }, "FixedAssetCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "kind", "source_type", "acquired_on", "in_use_on", "starts_on", "residual_value", "acquisition_account_public_id", "accumulated_account_public_id", "expense_account_public_id", "state_hash" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "enum": [ "equipment", "machinery", "vehicle", "building", "land", "goodwill" ] }, "source_type": { "enum": [ "opening", "purchase" ] }, "acquired_on": { "type": "string", "format": "date" }, "in_use_on": { "type": "string", "format": "date" }, "starts_on": { "type": "string", "format": "date" }, "opening_cost": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_accumulated": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_adjustment": { "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_tax_depreciation": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "residual_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "land_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "remaining_months": { "type": [ "integer", "null" ], "minimum": 0 }, "acquisition_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "accumulated_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetAllocationInput" }, "maxItems": 500 }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetChangeInput" }, "maxItems": 500 }, "building_facts": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetBuildingFacts" }, { "type": "null" } ] }, "disposal": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetDisposalInput" }, { "type": "null" } ], "description": "Omission during update preserves the existing disposal; explicit null undoes it, subject to the current preview and open-year checks." }, "asset_vat_allocations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "maxItems": 500, "description": "Explicit cost shares for prior VAT revisions. Null asset_public_id denotes the asset being created/edited. Fully capitalized lines require a closing split." }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expected_end_on": { "type": [ "string", "null" ], "format": "date", "description": "Inclusive last expected day of useful life. Alternative to remaining_months, not a disposal date. Tax ceilings and building floors still apply." } }, "allOf": [ { "if": { "properties": { "source_type": { "const": "opening" } } }, "then": { "required": [ "opening_cost", "opening_accumulated", "opening_adjustment" ], "properties": { "opening_cost": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_accumulated": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_adjustment": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "allocations": { "maxItems": 0 } } }, "else": { "required": [ "allocations" ], "properties": { "opening_cost": { "type": "null" }, "opening_accumulated": { "type": "null" }, "opening_adjustment": { "type": "null" }, "opening_tax_depreciation": { "type": "null" } } } }, { "if": { "properties": { "kind": { "const": "building" } } }, "then": { "required": [ "land_value" ], "properties": { "land_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, { "if": { "properties": { "kind": { "not": { "const": "land" } } } }, "then": { "oneOf": [ { "required": [ "remaining_months" ], "properties": { "remaining_months": { "type": "integer", "minimum": 1 }, "expected_end_on": { "type": "null" } } }, { "required": [ "expected_end_on" ], "properties": { "expected_end_on": { "type": "string", "format": "date" }, "remaining_months": { "type": "null" } } } ] }, "else": { "properties": { "expected_end_on": { "type": "null" }, "remaining_months": { "type": [ "integer", "null" ], "enum": [ 0, null ] } } } }, { "if": { "properties": { "source_type": { "const": "purchase" } } }, "then": { "properties": { "allocations": { "minItems": 1 } } } } ], "description": "Full editable input, not a patch. Monetary values use base-currency decimal strings with up to four places. Source capacity, tax evidence and all affected assets are rechecked together. Clients cannot post free cost_delta changes. For depreciable assets supply exactly one positive remaining_months or expected_end_on. Dates must be on or after the later of starts_on and in_use_on. Months retain their existing calculation; end dates use the exact calendar-month/day fraction. No current-fiscal-year fallback is applied." }, "FixedAssetUpdatePreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "kind", "source_type", "acquired_on", "in_use_on", "starts_on", "residual_value", "acquisition_account_public_id", "accumulated_account_public_id", "expense_account_public_id", "expected_revision" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "enum": [ "equipment", "machinery", "vehicle", "building", "land", "goodwill" ] }, "source_type": { "enum": [ "opening", "purchase" ] }, "acquired_on": { "type": "string", "format": "date" }, "in_use_on": { "type": "string", "format": "date" }, "starts_on": { "type": "string", "format": "date" }, "opening_cost": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_accumulated": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_adjustment": { "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_tax_depreciation": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "residual_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "land_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "remaining_months": { "type": [ "integer", "null" ], "minimum": 0 }, "acquisition_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "accumulated_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetAllocationInput" }, "maxItems": 500 }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetChangeInput" }, "maxItems": 500 }, "building_facts": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetBuildingFacts" }, { "type": "null" } ] }, "disposal": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetDisposalInput" }, { "type": "null" } ], "description": "Omission during update preserves the existing disposal; explicit null undoes it, subject to the current preview and open-year checks." }, "asset_vat_allocations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "maxItems": 500, "description": "Explicit cost shares for prior VAT revisions. Null asset_public_id denotes the asset being created/edited. Fully capitalized lines require a closing split." }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 }, "expected_end_on": { "type": [ "string", "null" ], "format": "date", "description": "Inclusive last expected day of useful life. Alternative to remaining_months, not a disposal date. Tax ceilings and building floors still apply." } }, "allOf": [ { "if": { "properties": { "source_type": { "const": "opening" } } }, "then": { "required": [ "opening_cost", "opening_accumulated", "opening_adjustment" ], "properties": { "opening_cost": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_accumulated": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_adjustment": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "allocations": { "maxItems": 0 } } }, "else": { "required": [ "allocations" ], "properties": { "opening_cost": { "type": "null" }, "opening_accumulated": { "type": "null" }, "opening_adjustment": { "type": "null" }, "opening_tax_depreciation": { "type": "null" } } } }, { "if": { "properties": { "kind": { "const": "building" } } }, "then": { "required": [ "land_value" ], "properties": { "land_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, { "if": { "properties": { "kind": { "not": { "const": "land" } } } }, "then": { "oneOf": [ { "required": [ "remaining_months" ], "properties": { "remaining_months": { "type": "integer", "minimum": 1 }, "expected_end_on": { "type": "null" } } }, { "required": [ "expected_end_on" ], "properties": { "expected_end_on": { "type": "string", "format": "date" }, "remaining_months": { "type": "null" } } } ] }, "else": { "properties": { "expected_end_on": { "type": "null" }, "remaining_months": { "type": [ "integer", "null" ], "enum": [ 0, null ] } } } } ], "description": "Full editable input, not a patch. Monetary values use base-currency decimal strings with up to four places. Source capacity, tax evidence and all affected assets are rechecked together. Clients cannot post free cost_delta changes. For depreciable assets supply exactly one positive remaining_months or expected_end_on. Dates must be on or after the later of starts_on and in_use_on. Months retain their existing calculation; end dates use the exact calendar-month/day fraction. No current-fiscal-year fallback is applied." }, "FixedAssetUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "kind", "source_type", "acquired_on", "in_use_on", "starts_on", "residual_value", "acquisition_account_public_id", "accumulated_account_public_id", "expense_account_public_id", "expected_revision", "state_hash" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "enum": [ "equipment", "machinery", "vehicle", "building", "land", "goodwill" ] }, "source_type": { "enum": [ "opening", "purchase" ] }, "acquired_on": { "type": "string", "format": "date" }, "in_use_on": { "type": "string", "format": "date" }, "starts_on": { "type": "string", "format": "date" }, "opening_cost": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_accumulated": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_adjustment": { "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_tax_depreciation": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "residual_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "land_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "remaining_months": { "type": [ "integer", "null" ], "minimum": 0 }, "acquisition_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "accumulated_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetAllocationInput" }, "maxItems": 500 }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetChangeInput" }, "maxItems": 500 }, "building_facts": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetBuildingFacts" }, { "type": "null" } ] }, "disposal": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetDisposalInput" }, { "type": "null" } ], "description": "Omission during update preserves the existing disposal; explicit null undoes it, subject to the current preview and open-year checks." }, "asset_vat_allocations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "maxItems": 500, "description": "Explicit cost shares for prior VAT revisions. Null asset_public_id denotes the asset being created/edited. Fully capitalized lines require a closing split." }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 }, "expected_end_on": { "type": [ "string", "null" ], "format": "date", "description": "Inclusive last expected day of useful life. Alternative to remaining_months, not a disposal date. Tax ceilings and building floors still apply." } }, "allOf": [ { "if": { "properties": { "source_type": { "const": "opening" } } }, "then": { "required": [ "opening_cost", "opening_accumulated", "opening_adjustment" ], "properties": { "opening_cost": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_accumulated": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "opening_adjustment": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "allocations": { "maxItems": 0 } } }, "else": { "required": [ "allocations" ], "properties": { "opening_cost": { "type": "null" }, "opening_accumulated": { "type": "null" }, "opening_adjustment": { "type": "null" }, "opening_tax_depreciation": { "type": "null" } } } }, { "if": { "properties": { "kind": { "const": "building" } } }, "then": { "required": [ "land_value" ], "properties": { "land_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, { "if": { "properties": { "kind": { "not": { "const": "land" } } } }, "then": { "oneOf": [ { "required": [ "remaining_months" ], "properties": { "remaining_months": { "type": "integer", "minimum": 1 }, "expected_end_on": { "type": "null" } } }, { "required": [ "expected_end_on" ], "properties": { "expected_end_on": { "type": "string", "format": "date" }, "remaining_months": { "type": "null" } } } ] }, "else": { "properties": { "expected_end_on": { "type": "null" }, "remaining_months": { "type": [ "integer", "null" ], "enum": [ 0, null ] } } } } ], "description": "Full editable input, not a patch. Monetary values use base-currency decimal strings with up to four places. Source capacity, tax evidence and all affected assets are rechecked together. Clients cannot post free cost_delta changes. For depreciable assets supply exactly one positive remaining_months or expected_end_on. Dates must be on or after the later of starts_on and in_use_on. Months retain their existing calculation; end dates use the exact calendar-month/day fraction. No current-fiscal-year fallback is applied." }, "FixedAsset": { "type": "object", "additionalProperties": false, "required": [ "name", "kind", "source_type", "acquired_on", "in_use_on", "starts_on", "opening_cost", "opening_accumulated", "opening_adjustment", "opening_tax_depreciation", "residual_value", "land_value", "remaining_months", "acquisition_account_public_id", "accumulated_account_public_id", "expense_account_public_id", "allocations", "changes", "building_facts", "disposal", "public_id", "revision", "tax_regime", "source_removed", "accounts" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "enum": [ "equipment", "machinery", "vehicle", "building", "land", "goodwill" ] }, "source_type": { "enum": [ "opening", "purchase" ] }, "acquired_on": { "type": "string", "format": "date" }, "in_use_on": { "type": "string", "format": "date" }, "starts_on": { "type": "string", "format": "date" }, "opening_cost": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_accumulated": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_adjustment": { "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "opening_tax_depreciation": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "residual_value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "land_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "remaining_months": { "type": [ "integer", "null" ], "minimum": 0 }, "acquisition_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "accumulated_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "allocations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "document_public_id", "line_public_id", "effective_on", "amount", "source_revision", "source_hash", "source_evidence" ], "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "effective_on": { "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "source_revision": { "type": "integer", "minimum": 1 }, "source_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source_evidence": { "type": "object", "additionalProperties": true, "description": "Read-only historical purchase valuation evidence." } } } }, "changes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "effective_on", "residual_value", "land_value", "remaining_months", "reason", "cost_delta", "vat_fact_public_id", "source_evidence" ], "properties": { "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "effective_on": { "type": "string", "format": "date" }, "residual_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "land_value": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "remaining_months": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "reason": { "type": [ "string", "null" ], "maxLength": 255 }, "cost_delta": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "vat_fact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "source_evidence": { "type": [ "object", "null" ], "additionalProperties": true }, "expected_end_on": { "type": [ "string", "null" ], "format": "date", "description": "Inclusive last expected day of useful life. Alternative to remaining_months, not a disposal date. Tax ceilings and building floors still apply." } } } }, "building_facts": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetBuildingFacts" }, { "type": "null" } ] }, "disposal": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "disposed_on", "result_account_public_id", "sales_document_public_id", "sales_line_public_id", "proceeds" ], "properties": { "type": { "enum": [ "sale", "write_off" ] }, "disposed_on": { "type": "string", "format": "date" }, "result_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "sales_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "sales_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "proceeds": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, { "type": "null" } ] }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "tax_regime": { "enum": [ "income_tax", "corporate_tax", "none" ] }, "source_removed": { "type": "boolean" }, "accounts": { "type": "object", "additionalProperties": false, "required": [ "acquisition", "accumulated", "expense" ], "properties": { "acquisition": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "accumulated": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "expense": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } } } }, "expected_end_on": { "type": [ "string", "null" ], "format": "date", "description": "Inclusive last expected day of useful life. Alternative to remaining_months, not a disposal date. Tax ceilings and building floors still apply." } } }, "FixedAssetResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FixedAsset" } } }, "FixedAssetListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAsset" } }, "links": { "type": "object", "additionalProperties": false, "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } }, "meta": { "type": "object", "additionalProperties": false, "required": [ "per_page" ], "properties": { "per_page": { "type": "integer", "minimum": 1 } } } } }, "FixedAssetAffectedPreview": { "type": "object", "additionalProperties": false, "required": [ "name", "tax_regime", "as_of", "schedule", "mutations", "opening_book_value", "book_value", "disposal_result", "state_hash" ], "properties": { "name": { "type": "string" }, "tax_regime": { "enum": [ "income_tax", "corporate_tax", "none" ] }, "as_of": { "type": "string", "format": "date" }, "schedule": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "starts_on", "ends_on", "posting_date", "fiscal_year_public_id", "amount", "book_value" ], "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "posting_date": { "type": "string", "format": "date" }, "fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "mutations": { "$ref": "#/components/schemas/FixedAssetPostingMutations" }, "opening_book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "disposal_result": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetDisposalResult" }, { "type": "null" } ] }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "forecast": { "description": "Read-only projection up to 50 years after as_of. projection_limit indicates that the schedule continues beyond this view; useful life and actual due postings are not capped. Future WOZ gaps stop the projection without inventing evidence.", "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "rows", "status", "complete_through", "incomplete_from", "missing_woz_year" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "starts_on", "ends_on", "posting_date", "amount", "book_value" ], "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "posting_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "status": { "enum": [ "complete", "missing_woz", "currency_precision", "date_range", "projection_limit" ] }, "complete_through": { "type": [ "string", "null" ], "format": "date" }, "incomplete_from": { "type": [ "string", "null" ], "format": "date" }, "missing_woz_year": { "type": [ "integer", "null" ] } } }, { "type": "null" } ] }, "opening_basis": { "type": "object", "additionalProperties": false, "required": [ "presentation", "offset" ], "properties": { "presentation": { "type": "string", "enum": [ "purchase", "net", "gross", "unspecified" ] }, "offset": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } } } }, "FixedAssetPreview": { "type": "object", "additionalProperties": false, "required": [ "state_hash" ], "properties": { "tax_regime": { "enum": [ "income_tax", "corporate_tax", "none" ] }, "as_of": { "type": "string", "format": "date" }, "schedule": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "starts_on", "ends_on", "posting_date", "fiscal_year_public_id", "amount", "book_value" ], "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "posting_date": { "type": "string", "format": "date" }, "fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "mutations": { "$ref": "#/components/schemas/FixedAssetPostingMutations" }, "opening_book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "disposal_result": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetDisposalResult" }, { "type": "null" } ] }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "vat_allocation": { "type": "object", "additionalProperties": false, "required": [ "required", "remainders", "assigned" ], "properties": { "required": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "line_public_id", "occurred_on", "available_cost_delta", "current_cost_delta", "name" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "occurred_on": { "type": "string", "format": "date" }, "available_cost_delta": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "current_cost_delta": { "type": [ "string", "null" ], "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "name": { "type": "string" } } } }, "remainders": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "occurred_on", "cost_account_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "occurred_on": { "type": "string", "format": "date" }, "cost_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "assigned": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "occurred_on", "amount", "name" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "occurred_on": { "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "name": { "type": "string" } } } } } }, "affected_assets": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAssetAffectedPreview" } }, "forecast": { "description": "Read-only projection up to 50 years after as_of. projection_limit indicates that the schedule continues beyond this view; useful life and actual due postings are not capped. Future WOZ gaps stop the projection without inventing evidence.", "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "rows", "status", "complete_through", "incomplete_from", "missing_woz_year" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "starts_on", "ends_on", "posting_date", "amount", "book_value" ], "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "posting_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "book_value": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "status": { "enum": [ "complete", "missing_woz", "currency_precision", "date_range", "projection_limit" ] }, "complete_through": { "type": [ "string", "null" ], "format": "date" }, "incomplete_from": { "type": [ "string", "null" ], "format": "date" }, "missing_woz_year": { "type": [ "integer", "null" ] } } }, { "type": "null" } ] }, "opening_basis": { "type": "object", "additionalProperties": false, "required": [ "presentation", "offset" ], "properties": { "presentation": { "type": "string", "enum": [ "purchase", "net", "gross", "unspecified" ] }, "offset": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } } }, "description": "Complete financial preview, or required VAT shares while incomplete. An incomplete preview cannot be confirmed.", "allOf": [ { "if": { "required": [ "vat_allocation" ], "properties": { "vat_allocation": { "properties": { "required": { "minItems": 1 } } } } }, "then": true, "else": { "required": [ "tax_regime", "as_of", "schedule", "mutations", "opening_book_value", "book_value", "disposal_result", "state_hash" ] } } ] }, "FixedAssetPreviewResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FixedAssetPreview" } } }, "FixedAssetPurchaseChoices": { "type": "array", "maxItems": 500, "description": "Explicit allocation amounts require fixed_assets:write in addition to purchases:write, for preview and confirmation. Omit or send [] for automatic source-derived effects. Same-administration references only; amounts retain four-decimal base-currency precision.", "items": { "type": "object", "additionalProperties": false, "required": [ "asset_public_id", "document_public_id", "line_public_id", "amount" ], "properties": { "asset_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "FixedAssetVatPurchaseChoices": { "type": "array", "maxItems": 500, "description": "Explicit VAT-basis cost shares require fixed_assets:write in addition to purchases:write, for preview and confirmation. Root and asset identities belong to this administration. Fully capitalized source lines require a complete split; partial capitalization displays the unassigned cost difference. No proportional allocation is inferred.", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "asset_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "asset_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "UpdateSalesDocumentLineInput": { "type": "object", "required": [ "amount" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Stable identity of this existing document line. Preserve it when reordering or editing. Null denotes a new line. Omitting an identity on an asset-linked document does not reuse positional identities; provide explicit asset_disposals if the linked sale disappears." }, "no_vat_reason": { "type": [ "string", "null" ], "enum": [ "receipt_without_consideration", null ] }, "posting_purpose": { "type": "string", "enum": [ "revenue", "balance_settlement" ], "description": "Omitted means the established revenue meaning. Balance settlement is explicit and supported only for existing external invoices and credits." }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } }, "oneOf": [ { "required": [ "vat_treatment_code", "amount_mode" ], "not": { "required": [ "no_vat_reason" ], "properties": { "no_vat_reason": { "const": "receipt_without_consideration" } } } }, { "required": [ "no_vat_reason" ], "properties": { "no_vat_reason": { "const": "receipt_without_consideration" }, "margin_method": { "const": "none" } }, "not": { "required": [ "vat_treatment_code" ] } } ], "description": "Choose a VAT treatment, or explicitly choose receipt_without_consideration for a direct receipt (or an internal return of that original receipt). No automatic tax default. With the explicit reason the amount is used as entered; amount_mode has no VAT effect.", "allOf": [ { "if": { "required": [ "posting_purpose" ], "properties": { "posting_purpose": { "const": "balance_settlement" } } }, "then": { "required": [ "balance_ledger_account_public_id" ], "not": { "required": [ "revenue_ledger_account_public_id" ] } }, "else": { "not": { "required": [ "balance_ledger_account_public_id" ] }, "required": [ "revenue_ledger_account_public_id" ] } } ] }, "UpdateSalesCreditLineInput": { "type": "object", "required": [ "amount" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "original_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Stable identity of this existing document line. Preserve it when reordering or editing. Null denotes a new line. Omitting an identity on an asset-linked document does not reuse positional identities; provide explicit asset_disposals if the linked sale disappears." }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "posting_purpose": { "type": "string", "enum": [ "revenue", "balance_settlement" ], "description": "Omitted means the established revenue meaning. Balance settlement is explicit and supported only for existing external invoices and credits." }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } }, "anyOf": [ { "required": [ "original_line_public_id" ], "properties": { "original_line_public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "required": [ "original_line_number" ], "properties": { "original_line_number": { "type": "integer", "minimum": 1, "maximum": 100 } } } ], "allOf": [ { "if": { "required": [ "posting_purpose" ], "properties": { "posting_purpose": { "const": "balance_settlement" } } }, "then": { "required": [ "balance_ledger_account_public_id" ], "not": { "required": [ "revenue_ledger_account_public_id" ] } }, "else": { "not": { "required": [ "balance_ledger_account_public_id" ] } } } ] }, "UpdateIssuedInvoiceLineInput": { "type": "object", "required": [ "revenue_ledger_account_public_id", "vat_treatment_code", "amount_mode", "quantity", "unit_price" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "quantity": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "unit_price": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Stable identity of this existing document line. Preserve it when reordering or editing. Null denotes a new line. Omitting an identity on an asset-linked document does not reuse positional identities; provide explicit asset_disposals if the linked sale disappears." }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } } }, "UpdateIssuedCreditLineInput": { "type": "object", "required": [ "quantity", "unit_price" ], "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255 }, "revenue_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "destination_vat_category": { "type": [ "string", "null" ], "enum": [ "standard_goods", "reduced_goods", "digital_services", "reduced_digital_services", null ], "description": "Required only when destination VAT applies and the effective official catalog does not yield one unambiguous category. The destination country is derived from the selected contact." }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ], "pattern": "^\\d+(?:\\.\\d+)?$" }, "margin_evidence_reference": { "type": [ "string", "null" ], "maxLength": 191 }, "original_line_number": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "quantity": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "unit_price": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "original_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Stable identity of this existing document line. Preserve it when reordering or editing. Null denotes a new line. Omitting an identity on an asset-linked document does not reuse positional identities; provide explicit asset_disposals if the linked sale disappears." }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "destination_vat_reporting_route": { "type": [ "string", "null" ], "enum": [ "foreign_return", null ], "description": "Explicit local foreign return outside OSS when local registration is not recorded. No automatic route or registration is created. Omit unless deliberately selected." } }, "anyOf": [ { "required": [ "original_line_public_id" ], "properties": { "original_line_public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "required": [ "original_line_number" ], "properties": { "original_line_number": { "type": "integer", "minimum": 1, "maximum": 100 } } } ] }, "DeleteSalesDocumentRequest": { "type": "object", "required": [ "expected_revision", "state_hash" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "asset_disposals": { "$ref": "#/components/schemas/FixedAssetSaleChoices" } } }, "PreviewDeleteSalesDocumentRequest": { "type": "object", "required": [ "expected_revision" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "asset_disposals": { "$ref": "#/components/schemas/FixedAssetSaleChoices" } } }, "DeleteSalesSourceRequest": { "type": "object", "required": [ "expected_revision", "state_hash" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "PreviewDeleteSalesSourceRequest": { "type": "object", "required": [ "expected_revision" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } }, "SalesAffectedResource": { "type": "object", "required": [ "type", "public_id", "revision", "effect" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "sales_document", "sales_settlement", "journal_entry" ] }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 0 }, "effect": { "type": "string" }, "document_type": { "type": "string", "enum": [ "external_invoice", "direct_sale", "external_credit_note" ] }, "settlement_type": { "type": "string", "enum": [ "receipt", "refund" ] }, "administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "entry_number": { "type": [ "integer", "null" ], "minimum": 1 }, "number": { "type": [ "string", "null" ] } } }, "SalesRouteDeltaPosition": { "type": "object", "required": [ "administration_public_id", "effect", "journal_entry_public_id", "journal_entry_revision", "entry_number", "number" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "effect": { "type": "string", "enum": [ "update_in_place", "create", "tombstone" ] }, "journal_entry_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "journal_entry_revision": { "type": "integer", "minimum": 0 }, "entry_number": { "type": "integer", "minimum": 1 }, "number": { "type": "string", "pattern": "^J[0-9]{6}$" } } }, "SalesDeletePreview": { "type": "object", "required": [ "state_hash", "affected_resources" ], "additionalProperties": false, "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "edit_mode": { "type": "null" }, "affected_resources": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/SalesAffectedResource" } }, "dependency_replans": { "type": "array", "items": { "$ref": "#/components/schemas/SalesAffectedResource" } }, "route_delta": { "type": "array", "items": { "$ref": "#/components/schemas/SalesRouteDeltaPosition" } }, "asset_correction": { "$ref": "#/components/schemas/FixedAssetSalesCorrection" } } }, "SalesDeletePreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SalesDeletePreview" } } }, "SalesSettlementDeletePreviewResponse": { "oneOf": [ { "$ref": "#/components/schemas/SalesDeletePreviewResponse" }, { "$ref": "#/components/schemas/SalesDocumentPreviewResponse" } ] }, "PutSalesAccountMappingsRequest": { "type": "object", "required": [ "trade_receivables", "deferred_output_vat_payable", "customer_refunds_payable", "payment_difference_gain", "payment_difference_loss" ], "additionalProperties": false, "properties": { "trade_receivables": { "$ref": "#/components/schemas/Ulid" }, "deferred_output_vat_payable": { "$ref": "#/components/schemas/Ulid" }, "customer_refunds_payable": { "$ref": "#/components/schemas/Ulid" }, "payment_difference_gain": { "$ref": "#/components/schemas/Ulid" }, "payment_difference_loss": { "$ref": "#/components/schemas/Ulid" } } }, "SalesReferenceIdentity": { "type": "object", "required": [ "public_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" } } }, "SalesPublicIdentity": { "type": "object", "required": [ "public_id", "name", "restricted" ], "additionalProperties": false, "properties": { "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "name": { "type": "string" }, "restricted": { "type": "boolean" } } }, "SalesLedgerIdentity": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "SalesPartySnapshot": { "type": "object", "required": [ "name", "country_code", "vat_identification_number" ], "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "vat_identification_number": { "type": [ "string", "null" ] } } }, "SalesCreditSplit": { "type": "object", "required": [ "native_receivable_reduction", "native_refund_liability", "base_receivable_reduction", "base_receivable_carrying_reduction", "base_refund_liability", "base_fx_result_amount" ], "additionalProperties": false, "properties": { "native_receivable_reduction": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_refund_liability": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_receivable_reduction": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_receivable_carrying_reduction": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_refund_liability": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_fx_result_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } }, "SalesViesSnapshot": { "type": "object", "required": [ "source", "result", "verified_at" ], "additionalProperties": false, "properties": { "source": { "type": "string", "enum": [ "official", "manual_evidence" ] }, "result": { "type": "string", "enum": [ "valid", "invalid" ] }, "verified_at": { "type": "string", "format": "date-time" } } }, "SalesDocumentStoredFx": { "type": "object", "additionalProperties": false, "required": [ "rate_numerator", "rate_denominator", "input", "formula_version" ], "properties": { "rate_numerator": { "type": "string" }, "rate_denominator": { "type": "string" }, "formula_version": { "type": "integer", "const": 1 }, "input": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "object", "additionalProperties": false, "required": [ "conversion_mode" ], "properties": { "conversion_mode": { "const": "original" }, "original_document_public_id": { "$ref": "#/components/schemas/Ulid" } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] } ] } } }, "SalesStoredFxSnapshot": { "type": "object", "required": [ "foreign_currency", "base_currency", "source_foreign_amount", "converted_base_amount", "input_mode", "rate_numerator", "rate_denominator", "convention", "effective_date", "formula_version", "input_value" ], "additionalProperties": false, "properties": { "foreign_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "source_foreign_amount": { "type": "string", "pattern": "^\\d+\\.\\d{4}$" }, "converted_base_amount": { "type": "string", "pattern": "^\\d+\\.\\d{4}$" }, "input_mode": { "type": "string", "enum": [ "rate", "converted_amount", "derived" ] }, "rate_numerator": { "type": "string" }, "rate_denominator": { "type": "string" }, "convention": { "type": "string", "const": "base_per_foreign_unit" }, "effective_date": { "type": "string", "format": "date" }, "formula_version": { "type": "integer", "const": 1 }, "input_value": { "type": [ "string", "null" ], "maxLength": 40 } } }, "SalesSettlementStoredFx": { "type": "object", "required": [ "document_to_base", "receipt_to_base" ], "additionalProperties": false, "properties": { "document_to_base": { "oneOf": [ { "$ref": "#/components/schemas/SalesStoredFxSnapshot" }, { "type": "null" } ] }, "receipt_to_base": { "oneOf": [ { "$ref": "#/components/schemas/SalesStoredFxSnapshot" }, { "type": "null" } ] } } }, "SalesSettlementPreviewFx": { "type": "object", "required": [ "document_to_base", "receipt_to_base" ], "additionalProperties": false, "properties": { "document_to_base": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxSnapshot" }, { "type": "null" } ] }, "receipt_to_base": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxSnapshot" }, { "type": "null" } ] } } }, "SalesPaymentDifference": { "type": "object", "required": [ "treatment", "document_amount", "base_carrying_amount", "base_amount" ], "additionalProperties": false, "properties": { "treatment": { "type": [ "string", "null" ], "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_customer_credit", null ] }, "document_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } }, "SalesCustomerCreditPreview": { "type": "object", "required": [ "currency_code", "amount", "base_carrying_amount", "status" ], "additionalProperties": false, "properties": { "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "status": { "type": "string", "const": "open" } } }, "SalesDirectSettlementPreview": { "type": "object", "required": [ "receipt_currency_code", "receipt_amount", "document_currency_amount", "receipt_base_amount", "base_settlement_amount", "base_carrying_amount", "base_fx_result_amount", "payment_difference", "customer_credit", "receipt_fx", "vat_releases" ], "additionalProperties": false, "properties": { "receipt_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "receipt_amount": { "type": "string" }, "document_currency_amount": { "type": "string" }, "receipt_base_amount": { "type": "string" }, "base_settlement_amount": { "type": "string" }, "base_carrying_amount": { "type": "string" }, "base_fx_result_amount": { "type": "string" }, "payment_difference": { "$ref": "#/components/schemas/SalesPaymentDifference" }, "customer_credit": { "oneOf": [ { "$ref": "#/components/schemas/SalesCustomerCreditPreview" }, { "type": "null" } ] }, "receipt_fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxSnapshot" }, { "type": "null" } ] }, "vat_releases": { "type": "array", "items": { "$ref": "#/components/schemas/SalesVatReleasePreview" } } } }, "SalesJournalLink": { "type": "object", "required": [ "administration_public_id", "journal_entry_public_id", "entry_number", "number", "source_type" ], "additionalProperties": false, "properties": { "administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "journal_entry_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "entry_number": { "type": [ "integer", "null" ], "minimum": 1 }, "number": { "type": [ "string", "null" ], "pattern": "^J[0-9]{6,}$" }, "source_type": { "type": "string", "enum": [ "sales_document", "sales_settlement" ] } } }, "SalesOpenItem": { "type": "object", "required": [ "native_original", "base_original", "native_receipts", "base_carrying_receipts", "native_credits", "base_carrying_credits", "native_outstanding", "base_carrying_outstanding", "status" ], "additionalProperties": false, "properties": { "native_original": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_original": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_receipts": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_receipts": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_credits": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_credits": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "status": { "type": "string", "enum": [ "open", "partially_paid", "paid", "credited" ] }, "base_book_outstanding": { "type": "string", "description": "Current outstanding book value after the existing bad-debt write-off; carrying history remains separate." }, "write_off": { "type": [ "object", "null" ], "description": "Existing bad-debt source and current outstanding position, or null when no write-off exists." } } }, "SalesDocumentLine": { "type": "object", "required": [ "line_number", "description", "amount_mode", "native_input_amount", "native_net_amount", "native_vat_amount", "native_gross_amount", "base_net_amount", "base_vat_amount", "base_gross_amount", "margin_method", "margin_purchase_amount", "margin_evidence_reference", "vat_fact", "calculation_trace", "public_id", "original_line_public_id" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer", "minimum": 1 }, "description": { "type": [ "string", "null" ] }, "revenue_account": { "oneOf": [ { "$ref": "#/components/schemas/SalesLedgerIdentity" }, { "type": "null" } ] }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "native_input_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_net_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_vat_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_gross_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_net_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_vat_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_gross_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "margin_method": { "type": "string", "enum": [ "none", "individual", "globalisation" ] }, "margin_purchase_amount": { "type": [ "string", "null" ] }, "margin_evidence_reference": { "type": [ "string", "null" ] }, "vat_fact": { "$ref": "#/components/schemas/SalesPublicVatFact" }, "calculation_trace": { "$ref": "#/components/schemas/SalesPublicCalculationTrace" }, "quantity": { "anyOf": [ { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, { "type": "null" } ] }, "unit_price": { "anyOf": [ { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, { "type": "null" } ] }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "original_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "original_opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "original_opening_vat_part_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_purpose": { "type": "string", "enum": [ "revenue", "balance_settlement" ] }, "local_rc_binding": { "type": [ "object", "null" ], "description": "Current own-administration binding by public configuration, position and ledger IDs plus role and financial properties. No internal IDs and no inter-administration route." }, "balance_account": { "oneOf": [ { "$ref": "#/components/schemas/SalesLedgerIdentity" }, { "type": "null" } ] } } }, "SalesCustomerCredit": { "type": "object", "required": [ "public_id", "contact", "source_document_public_id", "source_settlement_public_id", "credit_origin", "currency_code", "base_currency_code", "native_original", "native_refunded", "native_outstanding", "base_carrying_original", "base_carrying_released", "base_carrying_outstanding", "status", "revision", "created_at" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "contact": { "type": "object", "required": [ "public_id", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" } } }, "source_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "source_settlement_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_origin": { "type": "string", "enum": [ "settlement_excess", "external_credit_note" ] }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_original": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_refunded": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_original": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_released": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "status": { "type": "string", "enum": [ "open", "partially_refunded", "refunded" ] }, "revision": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "refund": { "oneOf": [ { "type": "object", "required": [ "currency_amount", "base_settlement_amount", "base_carrying_amount", "base_fx_result_amount" ], "additionalProperties": false, "properties": { "currency_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_settlement_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_fx_result_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } }, { "type": "null" } ] }, "source_opening_item_public_id": { "$ref": "#/components/schemas/Ulid" } } }, "SalesCustomerCreditCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCustomerCredit" } } } }, "SalesSettlement": { "type": "object", "required": [ "public_id", "document_public_id", "settlement_type", "settlement_purpose", "channel", "receiving_administration", "settlement_account", "settlement_date", "description", "receipt_currency_code", "base_currency_code", "receipt_amount", "receipt_base_amount", "document_currency_amount", "base_settlement_amount", "base_carrying_amount", "base_fx_result_amount", "payment_difference", "customer_credit", "fx", "vat_releases", "route", "revision", "status", "deleted_at" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "settlement_type": { "type": "string", "enum": [ "receipt", "refund" ] }, "settlement_purpose": { "type": "string", "enum": [ "receipt", "refund", "customer_credit_refund" ] }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration": { "oneOf": [ { "$ref": "#/components/schemas/SalesPublicIdentity" }, { "type": "null" } ] }, "settlement_account": { "oneOf": [ { "$ref": "#/components/schemas/SalesLedgerIdentity" }, { "type": "null" } ] }, "settlement_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "receipt_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "base_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "receipt_amount": { "type": [ "string", "null" ] }, "receipt_base_amount": { "type": [ "string", "null" ] }, "document_currency_amount": { "type": [ "string", "null" ] }, "base_settlement_amount": { "type": [ "string", "null" ] }, "base_carrying_amount": { "type": [ "string", "null" ] }, "base_fx_result_amount": { "type": [ "string", "null" ] }, "payment_difference": { "oneOf": [ { "$ref": "#/components/schemas/SalesPaymentDifference" }, { "type": "null" } ] }, "customer_credit": { "oneOf": [ { "$ref": "#/components/schemas/SalesCustomerCredit" }, { "type": "null" } ] }, "fx": { "$ref": "#/components/schemas/SalesSettlementStoredFx" }, "vat_releases": { "type": "array", "items": { "$ref": "#/components/schemas/SalesVatReleasePreview" } }, "route": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountPersistedRoute" }, { "type": "null" } ] }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SalesJournalLink" } }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "posted" ] }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "opening_item_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } } }, "SalesSettlementTombstone": { "type": "object", "required": [ "public_id", "resource_type", "settlement_type", "document_public_id", "status", "revision", "state_hash", "deleted_at", "deleted_by", "journal_entries" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "resource_type": { "type": "string", "const": "sales_settlement" }, "settlement_type": { "type": "string", "enum": [ "receipt", "refund" ] }, "document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "status": { "type": "string", "const": "deleted" }, "revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "deleted_at": { "type": "string", "format": "date-time" }, "deleted_by": { "oneOf": [ { "$ref": "#/components/schemas/SalesReferenceIdentity" }, { "type": "null" } ] }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SalesJournalLink" } } } }, "SalesDocument": { "type": "object", "required": [ "public_id", "document_type", "credit_source_type", "original_external_number", "original_external_date", "contact", "invoice_date", "supply_date", "due_date", "description", "currency_code", "base_currency_code", "native_net_amount", "native_vat_amount", "native_gross_amount", "base_net_amount", "base_vat_amount", "base_gross_amount", "credit_split", "vies", "fx", "status", "open_item", "revision", "deleted_at" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "document_type": { "type": "string", "enum": [ "external_invoice", "direct_sale", "external_credit_note", "issued_invoice", "issued_credit_note" ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ] }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact": { "oneOf": [ { "$ref": "#/components/schemas/SalesReferenceIdentity" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ] }, "invoice_date": { "type": [ "string", "null" ], "format": "date" }, "supply_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "currency_code": { "type": [ "string", "null" ] }, "base_currency_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "native_net_amount": { "type": [ "string", "null" ] }, "native_vat_amount": { "type": [ "string", "null" ] }, "native_gross_amount": { "type": [ "string", "null" ] }, "base_net_amount": { "type": [ "string", "null" ] }, "base_vat_amount": { "type": [ "string", "null" ] }, "base_gross_amount": { "type": [ "string", "null" ] }, "credit_split": { "$ref": "#/components/schemas/SalesCreditSplit" }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesSnapshot" }, { "type": "null" } ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesDocumentStoredFx" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "partially_paid", "paid", "credited" ] }, "open_item": { "oneOf": [ { "$ref": "#/components/schemas/SalesOpenItem" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SalesDocumentLine" } }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/SalesSettlement" } }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SalesJournalLink" } }, "route": { "$ref": "#/components/schemas/CurrentAccountPersistedRoute" }, "revision": { "type": "integer", "minimum": 1 }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "issued_number": { "type": [ "string", "null" ] }, "invoice_details": { "$ref": "#/components/schemas/InvoiceDetails" }, "original_documents": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCreditOrigin" }, "maxItems": 100 }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewNotice" } } }, "allOf": [ { "if": { "required": [ "document_type" ], "properties": { "document_type": { "enum": [ "issued_invoice", "issued_credit_note" ] } } }, "then": { "required": [ "issued_number", "invoice_details" ], "properties": { "lines": { "items": { "required": [ "quantity", "unit_price", "invoice_margin_category" ] } } } } }, { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "SalesDocumentTombstone": { "type": "object", "required": [ "public_id", "resource_type", "document_type", "credit_source_type", "external_number", "status", "revision", "state_hash", "deleted_at", "deleted_by", "journal_entries" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "resource_type": { "type": "string", "const": "sales_document" }, "document_type": { "type": "string", "enum": [ "external_invoice", "direct_sale", "external_credit_note", "issued_invoice", "issued_credit_note" ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ] }, "status": { "type": "string", "const": "deleted" }, "revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "deleted_at": { "type": "string", "format": "date-time" }, "deleted_by": { "oneOf": [ { "$ref": "#/components/schemas/SalesReferenceIdentity" }, { "type": "null" } ] }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SalesJournalLink" } }, "issued_number": { "type": [ "string", "null" ] } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "SalesDocumentResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/SalesDocument" }, { "$ref": "#/components/schemas/SalesDocumentTombstone" } ] } } }, "SalesDocumentTombstoneResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SalesDocumentTombstone" } } }, "SalesSettlementResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/SalesSettlement" }, { "$ref": "#/components/schemas/SalesSettlementTombstone" } ] } } }, "SalesSettlementTombstoneResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SalesSettlementTombstone" } } }, "SalesDocumentCollection": { "type": "object", "required": [ "data", "links" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SalesDocument" }, { "$ref": "#/components/schemas/SalesDocumentTombstone" } ] } }, "links": { "$ref": "#/components/schemas/CursorLinks" } } }, "SalesSettlementCollection": { "type": "object", "required": [ "data", "links" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SalesSettlement" }, { "$ref": "#/components/schemas/SalesSettlementTombstone" } ] } }, "links": { "$ref": "#/components/schemas/CursorLinks" } } }, "SalesFxSnapshot": { "type": "object", "required": [ "foreign_currency", "base_currency", "source_foreign_amount", "converted_base_amount", "rate_numerator", "rate_denominator", "convention", "effective_date", "formula_version" ], "additionalProperties": false, "properties": { "foreign_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "source_foreign_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "converted_base_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "rate_numerator": { "type": "string", "pattern": "^[1-9]\\d*$" }, "rate_denominator": { "type": "string", "pattern": "^[1-9]\\d*$" }, "convention": { "type": "string", "const": "base_per_foreign_unit" }, "effective_date": { "type": "string", "format": "date" }, "formula_version": { "type": "integer", "const": 1 } } }, "SalesPreviewOpenItem": { "type": "object", "required": [ "native_before", "native_after", "base_before", "base_after" ], "additionalProperties": false, "properties": { "native_before": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_after": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_before": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_after": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } }, "SalesPreviewVatExplanation": { "type": "object", "required": [ "tax_point_system", "recognition", "deferred", "cash_vat_released", "release_count" ], "additionalProperties": false, "properties": { "tax_point_system": { "type": "string", "enum": [ "invoice", "cash", "mixed" ] }, "recognition": { "type": "string", "enum": [ "invoice_or_supply_date", "on_receipt", "per_line" ] }, "deferred": { "type": "boolean" }, "cash_vat_released": { "type": "boolean" }, "release_count": { "type": "integer", "minimum": 0 } } }, "SalesSettlementVatExplanation": { "type": "object", "required": [ "cash_vat_released", "release_count" ], "additionalProperties": false, "properties": { "cash_vat_released": { "type": "boolean" }, "release_count": { "type": "integer", "minimum": 0 } } }, "SalesPreviewFxExplanation": { "type": "object", "required": [ "foreign_currency", "realized_result_amount" ], "additionalProperties": false, "properties": { "foreign_currency": { "type": "boolean" }, "transaction_rate_snapshot": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxSnapshot" }, { "type": "null" } ] }, "document_rate_snapshot": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxSnapshot" }, { "type": "null" } ] }, "receipt_rate_snapshot": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxSnapshot" }, { "type": "null" } ] }, "realized_result_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } }, "SalesPreviewNotice": { "type": "object", "required": [ "code" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "line_number": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "SalesPreviewJournalLine": { "type": "object", "required": [ "ledger_account_public_id", "code", "name", "category", "side", "debit", "credit", "native_currency_code", "native_amount", "base_currency_code", "base_amount", "amount" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "revenue", "vat", "receivable", "receipt", "rc", "fx", "payment_difference", "customer_credit", "credit", "refund", "fx_revaluation", "fx_periodic_adjustment", "bad_debt", "balance_settlement" ] }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "debit": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "credit": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "native_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "exact_amount": { "type": "boolean", "description": "True when the proved journal carrying amount requires its exact decimals instead of currency display rounding." } } }, "SalesPreviewJournalEntry": { "type": "object", "required": [ "entry_number", "fiscal_year_public_id", "lines", "administration_public_id", "administration_name", "currency_code", "date", "source", "fx_state_hash", "total_debit", "total_credit", "balanced" ], "additionalProperties": false, "properties": { "before": { "$ref": "#/components/schemas/CurrencyExchangeJournal", "description": "Original physical valuation journal before replacing its existing lines." }, "before_label": { "type": "string" }, "after_label": { "type": "string" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_name": { "type": "string" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "date": { "type": "string", "format": "date" }, "source": { "type": "string", "enum": [ "sales_document", "sales_settlement", "fx_revaluation", "fx_periodic_adjustment", "sales_write_off" ] }, "entry_number": { "type": "string" }, "fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "fx_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "heading": { "type": "string", "description": "Localized heading for an additional existing periodic currency valuation." }, "description": { "type": "string", "maxLength": 255 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewJournalLine" } }, "total_debit": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "total_credit": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "balanced": { "type": "boolean" } } }, "SalesDocumentPreviewLine": { "type": "object", "required": [ "line_number", "description", "vat_treatment_code", "vat_treatment_version", "vat_date", "correction_vat_date", "vat_date_derivation", "amount_mode", "native_net_amount", "native_vat_amount", "native_gross_amount", "base_net_amount", "base_vat_amount", "base_gross_amount", "vat_profile", "deferred", "deferred_reason", "cash_credit_split", "eu_b2c", "reporting_effects", "trace" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "vat_treatment_code": { "type": [ "string", "null" ] }, "vat_treatment_version": { "type": [ "integer", "null" ] }, "vat_date": { "type": [ "string", "null" ], "format": "date" }, "correction_vat_date": { "type": [ "string", "null" ], "format": "date" }, "vat_date_derivation": { "type": [ "string", "null" ] }, "amount_mode": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "native_net_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "native_vat_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "native_gross_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_net_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_vat_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_gross_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "vat_profile": { "oneOf": [ { "$ref": "#/components/schemas/SalesLineVatProfile" }, { "$ref": "#/components/schemas/SalesOpeningFiscalContext" } ] }, "deferred": { "type": "boolean" }, "deferred_reason": { "type": [ "string", "null" ] }, "cash_credit_split": { "oneOf": [ { "$ref": "#/components/schemas/SalesCashCreditSplit" }, { "type": "null" } ] }, "eu_b2c": { "oneOf": [ { "$ref": "#/components/schemas/SalesPublicEuB2c" }, { "type": "null" } ] }, "reporting_effects": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPublicReportingEffect" } }, "trace": { "$ref": "#/components/schemas/SalesPublicCalculationTrace" }, "quantity": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "unit_price": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "invoice_margin_category": { "type": [ "string", "null" ], "enum": [ "used_goods", "art", "collectors_antiques", null ] }, "no_vat_reason": { "type": [ "string", "null" ], "enum": [ "receipt_without_consideration", null ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "original_line_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "original_opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "original_opening_vat_part_public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_purpose": { "type": "string", "enum": [ "revenue", "balance_settlement" ] }, "local_rc_binding": { "type": [ "object", "null" ], "description": "Current own-administration binding by public configuration, position and ledger IDs plus role and financial properties. No internal IDs and no inter-administration route." }, "balance_account": { "type": [ "object", "null" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } } } }, "SalesDocumentPreview": { "type": "object", "required": [ "state_hash", "asset_correction", "document_type", "description", "currency_code", "contact", "credit_source_type", "original_external_number", "original_external_date", "contact_requirement", "vat_profile", "lines", "totals", "credit_split", "vies", "vies_proof", "fx", "settlement_plan", "vat_releases", "open_item", "vat_explanation", "fx_explanation", "warnings", "blockers", "route", "journal_entry", "journal_entries", "administrations" ], "additionalProperties": false, "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "document_type": { "type": "string" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "contact": { "oneOf": [ { "$ref": "#/components/schemas/SalesReferenceIdentity" }, { "type": "null" } ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ] }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "vat_profile": { "type": "object", "required": [ "tax_point_system", "vat_regime", "rounding_method", "revision", "mixed" ], "additionalProperties": false, "properties": { "tax_point_system": { "type": "string", "enum": [ "invoice", "cash", "mixed" ] }, "vat_regime": { "type": [ "string", "null" ], "enum": [ "standard", "kor", "not_registered", "mixed", null ] }, "rounding_method": { "type": [ "string", "null" ], "enum": [ "per_supply", "document_total", "mixed", null ] }, "revision": { "type": [ "integer", "null" ], "minimum": 1 }, "mixed": { "type": "boolean" } } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SalesDocumentPreviewLine" } }, "totals": { "type": "object", "required": [ "native_net_amount", "native_vat_amount", "native_gross_amount", "base_net_amount", "base_vat_amount", "base_gross_amount" ], "additionalProperties": false, "properties": { "native_net_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "native_vat_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "native_gross_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_net_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_vat_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_gross_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" } } }, "credit_split": { "$ref": "#/components/schemas/SalesCreditSplit" }, "vies": { "oneOf": [ { "type": "object", "required": [ "country_code", "vat_number", "source", "result", "verified_at", "request_reference", "evidence_reference", "registered_name" ], "additionalProperties": false, "properties": { "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "vat_number": { "type": "string" }, "source": { "type": "string", "enum": [ "official", "manual_evidence" ] }, "result": { "type": "string", "enum": [ "valid", "invalid", "unavailable" ] }, "verified_at": { "type": "string", "format": "date-time" }, "request_reference": { "type": [ "string", "null" ] }, "evidence_reference": { "type": [ "string", "null" ] }, "registered_name": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "vies_proof": { "type": [ "string", "null" ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxSnapshot" }, { "type": "null" } ] }, "settlement_plan": { "oneOf": [ { "$ref": "#/components/schemas/SalesSettlementPreview" }, { "type": "null" } ] }, "contact_requirement": { "type": "object", "required": [ "required", "reason", "currency_code", "open_amount", "customer_credit_amount" ], "additionalProperties": false, "properties": { "required": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "enum": [ "document_type", "open_amount", "customer_credit", null ] }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "open_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "customer_credit_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" } } }, "vat_releases": { "type": "array", "items": { "$ref": "#/components/schemas/SalesVatReleasePreview" } }, "open_item": { "$ref": "#/components/schemas/SalesPreviewOpenItem" }, "vat_explanation": { "$ref": "#/components/schemas/SalesPreviewVatExplanation" }, "fx_explanation": { "$ref": "#/components/schemas/SalesPreviewFxExplanation" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewNotice" } }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewNotice" } }, "route": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountLiveRoute" }, { "type": "null" } ] }, "journal_entry": { "$ref": "#/components/schemas/SalesPreviewJournalEntry" }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewJournalEntry" } }, "administrations": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewJournalEntry" } }, "edit_mode": { "oneOf": [ { "type": "string", "enum": [ "in_place_update", "no_change" ] }, { "type": "null" } ] }, "affected_resources": { "type": "array", "items": { "$ref": "#/components/schemas/SalesAffectedResource" } }, "dependency_replans": { "type": "array", "items": { "$ref": "#/components/schemas/SalesAffectedResource" } }, "route_delta": { "type": "array", "items": { "$ref": "#/components/schemas/SalesRouteDeltaPosition" } }, "asset_correction": { "oneOf": [ { "$ref": "#/components/schemas/FixedAssetSalesCorrection" }, { "type": "null" } ] }, "original_documents": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCreditOrigin" }, "maxItems": 100 }, "historical_origins": { "type": "object", "required": [ "before", "after" ], "additionalProperties": false, "properties": { "before": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOrigin" } }, "after": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOrigin" } } } }, "original_opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "balance_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceDestinationPreview" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "SalesDocumentPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SalesDocumentPreview" } } }, "SalesVatReleasePreview": { "type": "object", "required": [ "line_number", "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount", "reporting_effects" ], "additionalProperties": false, "properties": { "line_number": { "type": "integer" }, "native_taxable_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "native_vat_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_taxable_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_vat_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "reporting_effects": { "type": "array", "items": { "$ref": "#/components/schemas/SalesVatReportingEffect" } } } }, "SalesVatReportingEffect": { "type": "object", "required": [ "scheme", "code", "component", "route_condition", "amount", "base_amount" ], "additionalProperties": false, "properties": { "scheme": { "type": "string" }, "code": { "type": "string" }, "component": { "type": "string" }, "route_condition": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "polarity": { "type": "string", "enum": [ "charge", "credit" ] } } }, "SalesSettlementPreview": { "type": "object", "required": [ "state_hash", "settlement_type", "description", "document", "receipt_currency_code", "receipt_amount", "document_currency_amount", "receipt_base_amount", "base_settlement_amount", "base_carrying_amount", "base_fx_result_amount", "payment_difference", "customer_credit", "vat_releases", "fx", "open_item", "vat_explanation", "fx_explanation", "warnings", "blockers", "route", "journal_entries", "administrations" ], "additionalProperties": false, "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "edit_mode": { "type": "string", "enum": [ "in_place_update", "no_change" ] }, "affected_resources": { "type": "array", "items": { "$ref": "#/components/schemas/SalesAffectedResource" } }, "dependency_replans": { "type": "array", "items": { "$ref": "#/components/schemas/SalesAffectedResource" } }, "route_delta": { "type": "array", "items": { "$ref": "#/components/schemas/SalesRouteDeltaPosition" } }, "settlement_type": { "type": "string", "enum": [ "receipt", "refund" ] }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "document": { "oneOf": [ { "type": "object", "required": [ "public_id", "external_number" ], "additionalProperties": false, "properties": { "public_id": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "source_type": { "const": "sales_document" } } }, { "type": "null" } ] }, "receipt_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "receipt_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "document_currency_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "receipt_base_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_settlement_amount": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "base_carrying_amount": { "type": "string", "maxLength": 32, "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "base_fx_result_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "payment_difference": { "$ref": "#/components/schemas/SalesPaymentDifference" }, "customer_credit": { "oneOf": [ { "$ref": "#/components/schemas/SalesCustomerCreditPreview" }, { "type": "null" } ] }, "settlement_purpose": { "type": "string", "enum": [ "customer_credit_refund" ] }, "customer_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_releases": { "type": "array", "items": { "$ref": "#/components/schemas/SalesVatReleasePreview" } }, "fx": { "$ref": "#/components/schemas/SalesSettlementPreviewFx" }, "route": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountLiveRoute" }, { "type": "null" } ] }, "edge_amounts": { "type": "array", "items": { "$ref": "#/components/schemas/SalesRouteEdgeAmountPreview" } }, "journal_entry": { "$ref": "#/components/schemas/SalesPreviewJournalEntry" }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewJournalEntry" } }, "open_item": { "$ref": "#/components/schemas/SalesPreviewOpenItem" }, "vat_explanation": { "$ref": "#/components/schemas/SalesSettlementVatExplanation" }, "fx_explanation": { "$ref": "#/components/schemas/SalesPreviewFxExplanation" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewNotice" } }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewNotice" } }, "administrations": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewJournalEntry" } }, "opening_item": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "source_type", "public_id", "reference" ], "properties": { "source_type": { "const": "opening_trade_item" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "reference": { "type": [ "string", "null" ] } } } ] }, "bad_debt_recovery": { "$ref": "#/components/schemas/SalesBadDebtRecoveryPreview" } } }, "SalesSettlementPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SalesSettlementPreview" } } }, "SalesSettlementUpdatePreviewResponse": { "oneOf": [ { "$ref": "#/components/schemas/SalesSettlementPreviewResponse" }, { "$ref": "#/components/schemas/SalesDocumentPreviewResponse" } ] }, "SalesReconciliationResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "ledger_balance", "open_items", "difference", "reconciled", "opening_balance", "expected_balance", "has_unspecified_opening_balance" ], "additionalProperties": false, "properties": { "ledger_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "open_items": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "difference": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "reconciled": { "type": "boolean" }, "opening_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "description": "Signed balance brought forward, to be specified separately." }, "opening_specification": { "oneOf": [ { "$ref": "#/components/schemas/OpeningTradeSpecification" }, { "type": "null" } ] }, "expected_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "description": "Recorded open items plus the opening balance, each counted once." }, "has_unspecified_opening_balance": { "type": "boolean", "description": "True when an opening total still lacks individual invoice specifications; a matching ledger is not proof of complete invoice coverage." } } } } }, "SalesOptionsResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "contacts", "vat_context", "vat_treatments", "revenue_accounts", "settlement_accounts" ], "additionalProperties": false, "properties": { "contacts": { "type": "array", "items": { "type": "object", "required": [ "public_id", "name", "country_code", "has_vat_identification_number" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "has_vat_identification_number": { "type": "boolean" } } } }, "vat_context": { "$ref": "#/components/schemas/SalesVatContextInput" }, "vat_treatments": { "type": "array", "items": { "type": "object", "required": [ "code", "label", "display_group", "mechanism", "requires_vies", "requires_destination_vat", "requires_margin_method" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "display_group": { "type": "string" }, "mechanism": { "type": "string" }, "requires_vies": { "type": "boolean" }, "requires_destination_vat": { "type": "boolean" }, "requires_margin_method": { "type": "boolean" } } } }, "revenue_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/SalesLedgerIdentity" } }, "settlement_accounts": { "type": "array", "items": { "type": "object", "required": [ "public_id", "code", "name", "classification", "currency_mode", "native_currency_code", "receipt_currency_code", "administration_public_id", "administration_currency_code", "derivation_source" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "classification": { "type": "string" }, "currency_mode": { "type": "string", "enum": [ "base_only", "fixed_foreign" ] }, "native_currency_code": { "type": [ "string", "null" ] }, "receipt_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "derivation_source": { "type": "string", "enum": [ "account_administration_currency", "account_fixed_foreign_currency" ] } } } }, "no_vat_reasons": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "reason", "label", "document_types" ], "properties": { "reason": { "const": "receipt_without_consideration" }, "label": { "type": "string" }, "document_types": { "type": "array", "items": { "const": "direct_sale" } } } } } } } } }, "SalesAccountMapping": { "type": "object", "required": [ "public_id", "code", "name", "revision" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "revision": { "type": "integer" } } }, "SalesAccountMappingsResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [], "additionalProperties": false, "properties": { "trade_receivables": { "$ref": "#/components/schemas/SalesAccountMapping" }, "deferred_output_vat_payable": { "$ref": "#/components/schemas/SalesAccountMapping" }, "customer_refunds_payable": { "$ref": "#/components/schemas/SalesAccountMapping" }, "payment_difference_gain": { "$ref": "#/components/schemas/SalesAccountMapping" }, "payment_difference_loss": { "$ref": "#/components/schemas/SalesAccountMapping" } } } } }, "UpdateSalesDocumentPreviewRequest": { "type": "object", "required": [ "document_type", "invoice_date", "supply_date", "lines", "expected_revision" ], "additionalProperties": false, "properties": { "document_type": { "type": "string", "enum": [ "external_invoice", "direct_sale", "external_credit_note", "issued_invoice", "issued_credit_note" ] }, "original_document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "credit_source_type": { "type": [ "string", "null" ], "enum": [ "internal", "external", null ] }, "original_external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "original_external_date": { "type": [ "string", "null" ], "format": "date" }, "contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "invoice_date": { "type": "string", "format": "date" }, "supply_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vat_context": { "oneOf": [ { "$ref": "#/components/schemas/SalesVatContextInput" }, { "type": "object", "maxProperties": 0 } ], "description": "Required for VAT-treated lines; omit for a receipt without consideration." }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/SalesFxInput" }, { "type": "null" } ] }, "vies": { "oneOf": [ { "$ref": "#/components/schemas/SalesViesInput" }, { "type": "null" } ] }, "vies_proof": { "type": [ "string", "null" ], "maxLength": 4096 }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "$ref": "#/components/schemas/UpdateSalesDocumentLineInput" }, { "$ref": "#/components/schemas/UpdateSalesCreditLineInput" }, { "$ref": "#/components/schemas/UpdateIssuedInvoiceLineInput" }, { "$ref": "#/components/schemas/UpdateIssuedCreditLineInput" } ] } }, "expected_revision": { "type": "integer", "minimum": 1 }, "asset_disposals": { "$ref": "#/components/schemas/FixedAssetSaleChoices" }, "original_document_public_ids": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" }, "description": "Internal credit sources, all in the same administration, customer and currency. Every credit line identifies one source." }, "historical_origin_changes": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOriginChange" }, "maxItems": 100, "description": "Explicitly keep, replace amounts or remove historical capacity reservations in the same financial correction preview. Unchanged reservations remain subject to both source and credit capacity checks." } }, "allOf": [ { "if": { "required": [ "document_type" ], "properties": { "document_type": { "enum": [ "issued_invoice", "issued_credit_note" ] } } }, "then": { "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "issued_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateIssuedCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "else": { "required": [ "currency_code", "contact_public_id" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateIssuedInvoiceLineInput" } } } } } ] }, "else": { "allOf": [ { "if": { "required": [ "document_type", "credit_source_type" ], "properties": { "document_type": { "const": "external_credit_note" }, "credit_source_type": { "const": "internal" } } }, "then": { "required": [], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateSalesCreditLineInput" } } }, "allOf": [ { "anyOf": [ { "required": [ "original_document_public_id" ] }, { "required": [ "original_document_public_ids" ] } ] } ] }, "else": { "required": [ "currency_code" ], "properties": { "lines": { "items": { "$ref": "#/components/schemas/UpdateSalesDocumentLineInput" } } } } } ] } } ] }, "SalesSettlementErrorCode": { "type": "string", "enum": [ "validation_failed", "sales_document_not_found", "sales_settlement_not_found", "sales_state_stale", "sales_settlement_stale", "sales_open_year_required", "sales_route_invalid", "sales_route_inactive", "sales_vat_release_reconciliation_failed", "fx_settlement_evidence_stale", "fx_state_stale", "idempotency_key_reused", "idempotency_key_required", "idempotency_key_invalid", "sales_route_administration_set_changed", "sales_tax_party_required", "sales_settlement_account_invalid", "sales_settlement_document_invalid", "sales_settlement_exceeds_outstanding", "sales_settlement_amount_mismatch", "sales_document_allocation_required", "sales_amount_invalid", "sales_fx_required", "sales_fx_unexpected", "sales_fx_account_unmapped", "sales_payment_difference_treatment_required", "sales_credit_number_required", "sales_payment_difference_not_present", "sales_payment_difference_not_allowed", "sales_customer_credit_not_found", "sales_customer_credit_unavailable", "sales_customer_credit_exceeds_outstanding", "sales_customer_credit_reconciliation_failed", "sales_dependency_stale", "sales_document_type_immutable", "sales_route_amounts_required", "sales_route_amounts_invalid", "sales_cross_administration_planner_required", "sales_direct_open_item_contact_required", "sales_customer_credit_contact_required", "sales_direct_settlement_delete_contact_required", "sales_account_role_unmapped" ] }, "SalesSettlementErrorEnvelope": { "type": "object", "required": [ "error", "request_id" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "additionalProperties": false, "properties": { "code": { "$ref": "#/components/schemas/SalesSettlementErrorCode" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "request_id": { "$ref": "#/components/schemas/Ulid" } } }, "PurchaseDecimal": { "type": "string", "maxLength": 32, "pattern": "^\\d+(?:\\.\\d+)?$" }, "PurchaseStateHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "PurchaseFxEvidence": { "type": "object", "required": [ "conversion_mode", "source", "observed_at" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "$ref": "#/components/schemas/PurchaseDecimal" }, "converted_base_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "source": { "type": "string", "maxLength": 80 }, "observed_at": { "type": "string", "format": "date-time" } }, "allOf": [ { "if": { "properties": { "conversion_mode": { "const": "rate" } } }, "then": { "required": [ "rate" ], "not": { "required": [ "converted_base_amount" ] } }, "else": { "required": [ "converted_base_amount" ], "not": { "required": [ "rate" ] } } } ] }, "PurchasePaymentFxInput": { "type": "object", "required": [ "conversion_mode" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "$ref": "#/components/schemas/PurchaseDecimal" }, "converted_base_amount": { "$ref": "#/components/schemas/PurchaseDecimal" } }, "allOf": [ { "if": { "properties": { "conversion_mode": { "const": "rate" } } }, "then": { "required": [ "rate" ], "not": { "required": [ "converted_base_amount" ] } }, "else": { "required": [ "converted_base_amount" ], "not": { "required": [ "rate" ] } } } ] }, "PurchaseLineInput": { "type": "object", "required": [ "ledger_account_public_id", "amount", "non_deductible_treatment", "margin_method" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional line note. Omitted, null or blank input is stored and returned as an empty string; no description is inferred. Supplied text retains the existing whitespace trimming." }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "amount_mode": { "type": "string", "enum": [ "exclusive", "inclusive" ] }, "invoice_vat_amount": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseDecimal" }, { "type": "null" }, { "type": "string", "const": "" } ] }, "deductible_percentage": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseDecimal" }, { "type": "null" }, { "type": "string", "const": "" } ] }, "non_deductible_treatment": { "type": "string", "const": "capitalise_on_line" }, "foreign_vat_country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "foreign_vat_disposition": { "type": "string", "enum": [ "expense", "reclaimable" ] }, "margin_method": { "type": "string", "enum": [ "none", "global_9", "global_21" ] }, "cost_period": { "$ref": "#/components/schemas/PurchaseCostPeriod" } }, "allOf": [ { "if": { "properties": { "margin_method": { "const": "none" } } }, "then": { "required": [ "vat_treatment_code", "amount_mode" ] }, "else": { "not": { "anyOf": [ { "required": [ "vat_treatment_code" ] }, { "required": [ "amount_mode" ] }, { "required": [ "invoice_vat_amount" ] }, { "required": [ "deductible_percentage" ] }, { "required": [ "foreign_vat_country_code" ] }, { "required": [ "foreign_vat_disposition" ] } ] } } }, { "if": { "properties": { "margin_method": { "const": "none" }, "vat_treatment_code": { "const": "purchase_nl_exempt" } }, "required": [ "margin_method", "vat_treatment_code" ] }, "then": { "properties": { "invoice_vat_amount": { "enum": [ null, "" ] }, "deductible_percentage": { "enum": [ null, "" ] } } }, "else": { "if": { "properties": { "margin_method": { "const": "none" } }, "required": [ "margin_method" ] }, "then": { "required": [ "deductible_percentage" ] } } } ], "description": "Explicit purchase_nl_exempt has no supplier VAT or deductible percentage: omit those fields or send null/blank. Nonempty values, including zero, are rejected. Returned stored deduction is zero because the exempt treatment has no VAT effect." }, "PurchaseCreateLineInput": { "allOf": [ { "$ref": "#/components/schemas/PurchaseLineInput" }, { "not": { "required": [ "public_id" ] } } ] }, "PurchaseAllocationInput": { "type": "object", "required": [ "amount" ], "additionalProperties": false, "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "opening_item_public_id": { "$ref": "#/components/schemas/Ulid" } }, "oneOf": [ { "required": [ "document_public_id" ], "not": { "required": [ "opening_item_public_id" ] } }, { "required": [ "opening_item_public_id" ], "not": { "required": [ "document_public_id" ] } } ] }, "PurchaseRouteBaseAmountInput": { "type": "object", "required": [ "administration_public_id", "base_amount" ], "additionalProperties": false, "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "base_amount": { "$ref": "#/components/schemas/PurchaseDecimal" } } }, "PurchaseRouteEdgeAmountInput": { "type": "object", "required": [ "configuration_public_id", "native_amount", "base_amounts" ], "additionalProperties": false, "properties": { "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "native_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "base_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/PurchaseRouteBaseAmountInput" } } } }, "PurchasePaymentFields": { "type": "object", "additionalProperties": false, "properties": { "supplier_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration", "loan_financing", "owner_private" ] }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Required only for current-account settlements: the explicitly selected existing contact of the own or a linked administration, independently of the supplier. The complete configured route and current write access to every involved administration are required." }, "payment_date": { "type": "string", "format": "date" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "document_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "difference_treatment": { "type": "string", "enum": [ "leave_open", "write_off_shortfall", "recognize_excess", "hold_supplier_credit" ] }, "fx": { "$ref": "#/components/schemas/PurchasePaymentFxInput" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/PurchaseRouteEdgeAmountInput" } }, "allocations": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchasePayableAllocationInput" } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 }, "loan_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Required only for loan_financing: an active borrowed loan in this administration with its eligible principal account. This additionally requires loans:write and loan management permission. No bank movement is created." }, "private_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Required only for owner_private: the actual payment currency. No business bank or cash account is created." }, "unallocated_payment": { "type": "boolean", "description": "Explicit payment without invoice allocation. True requires a supplier, zero allocations and the complete amount as supplier credit; no expense or VAT is created." } }, "allOf": [ { "if": { "properties": { "channel": { "const": "loan_financing" } }, "required": [ "channel" ] }, "then": { "required": [ "loan_public_id" ], "not": { "anyOf": [ { "required": [ "ledger_account_public_id" ] }, { "required": [ "receiving_administration_public_id" ] }, { "required": [ "payer_contact_public_id" ] } ] }, "properties": { "route_configuration_public_ids": { "maxItems": 0 }, "edge_amounts": { "maxItems": 0 } } }, "else": { "not": { "required": [ "loan_public_id" ] } } }, { "if": { "properties": { "channel": { "const": "owner_private" } }, "required": [ "channel" ] }, "then": { "required": [ "private_currency_code" ], "not": { "anyOf": [ { "required": [ "ledger_account_public_id" ] }, { "required": [ "payer_contact_public_id" ] }, { "required": [ "receiving_administration_public_id" ] } ] }, "properties": { "route_configuration_public_ids": { "maxItems": 0 }, "edge_amounts": { "maxItems": 0 } } }, "else": { "not": { "anyOf": [ { "required": [ "private_currency_code" ] } ] } } }, { "oneOf": [ { "properties": { "unallocated_payment": { "const": true }, "allocations": { "maxItems": 0 }, "difference_treatment": { "const": "hold_supplier_credit" }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" } }, "required": [ "unallocated_payment", "supplier_public_id" ] }, { "properties": { "unallocated_payment": { "const": false }, "allocations": { "minItems": 1 } } } ] } ] }, "PurchaseEmbeddedPaymentInput": { "allOf": [ { "$ref": "#/components/schemas/PurchasePaymentFields" }, { "type": "object", "required": [ "channel", "payment_date", "amount" ] } ], "unevaluatedProperties": false }, "PurchaseDocumentFields": { "type": "object", "additionalProperties": false, "properties": { "document_type": { "type": "string", "enum": [ "purchase", "supplier_credit_note" ] }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "supplier_vat_identification_number": { "type": [ "string", "null" ], "maxLength": 32 }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "document_date": { "type": "string", "format": "date" }, "performance_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fx": { "$ref": "#/components/schemas/PurchaseFxEvidence" }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseLineInput" } }, "payment": { "$ref": "#/components/schemas/PurchaseEmbeddedPaymentInput" }, "credit_allocations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseAllocationInput" } }, "acknowledged_duplicate_public_id": { "$ref": "#/components/schemas/Ulid" }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "PreviewPurchaseDocumentRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/PurchaseDocumentFields" }, { "type": "object", "required": [ "document_type", "document_date", "performance_date", "currency_code", "lines" ], "properties": { "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseCreateLineInput" } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "$ref": "#/components/schemas/PurchasePayrollFields" }, { "required": [] }, { "not": { "anyOf": [ { "required": [ "state_hash" ] }, { "required": [ "expected_revision" ] } ] } } ] } ] }, "PostPurchaseDocumentRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/PurchaseDocumentFields" }, { "type": "object", "required": [ "document_type", "document_date", "performance_date", "currency_code", "lines", "state_hash" ], "properties": { "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseCreateLineInput" } } } } ], "unevaluatedProperties": false }, { "allOf": [ { "$ref": "#/components/schemas/PurchasePayrollFields" }, { "required": [ "state_hash" ] }, { "not": { "anyOf": [ { "required": [ "expected_revision" ] } ] } } ] } ] }, "PurchaseUpdateDocumentFields": { "type": "object", "additionalProperties": false, "properties": { "document_type": { "type": "string", "enum": [ "purchase", "supplier_credit_note" ] }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "supplier_vat_identification_number": { "type": [ "string", "null" ], "maxLength": 32 }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "document_date": { "type": "string", "format": "date" }, "performance_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fx": { "$ref": "#/components/schemas/PurchaseFxEvidence" }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseLineInput" } }, "payment": { "$ref": "#/components/schemas/PurchaseEmbeddedPaymentInput" }, "credit_allocations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchaseAllocationInput" } }, "acknowledged_duplicate_public_id": { "$ref": "#/components/schemas/Ulid" }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 }, "vat_revisions": { "type": "array", "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "amount" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } }, "description": "Only when requested by the update preview: desired signed amount of the existing manual VAT revision. The same source, journal identity, J-number and original date are retained. Zero removes the financial effect, without appending a reversal." }, "asset_allocations": { "$ref": "#/components/schemas/FixedAssetPurchaseChoices" }, "asset_vat_allocations": { "$ref": "#/components/schemas/FixedAssetVatPurchaseChoices" } } }, "PreviewUpdatePurchaseDocumentRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/PurchaseUpdateDocumentFields" }, { "type": "object", "required": [ "document_type", "document_date", "performance_date", "currency_code", "lines", "expected_revision" ] } ], "unevaluatedProperties": false }, { "allOf": [ { "$ref": "#/components/schemas/PurchasePayrollFields" }, { "required": [ "expected_revision" ] }, { "not": { "required": [ "payment" ] } }, { "not": { "anyOf": [ { "required": [ "state_hash" ] } ] } } ] } ] }, "UpdatePurchaseDocumentRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/PurchaseUpdateDocumentFields" }, { "type": "object", "required": [ "document_type", "document_date", "performance_date", "currency_code", "lines", "state_hash", "expected_revision" ] } ], "unevaluatedProperties": false }, { "allOf": [ { "$ref": "#/components/schemas/PurchasePayrollFields" }, { "required": [ "state_hash", "expected_revision" ] }, { "not": { "required": [ "payment" ] } } ] } ] }, "PurchaseCreateSettlementFields": { "type": "object", "additionalProperties": false, "properties": { "supplier_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "channel": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/channel" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/receiving_administration_public_id" }, "ledger_account_public_id": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/ledger_account_public_id" }, "payer_contact_public_id": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/payer_contact_public_id" }, "payment_date": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/payment_date" }, "amount": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/amount" }, "document_currency_amount": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/document_currency_amount" }, "difference_treatment": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/difference_treatment" }, "fx": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/fx" }, "route_configuration_public_ids": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/route_configuration_public_ids" }, "edge_amounts": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/edge_amounts" }, "allocations": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/allocations" }, "state_hash": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/state_hash" }, "expected_revision": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/expected_revision" }, "loan_public_id": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/loan_public_id" }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." }, "private_currency_code": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/private_currency_code" }, "unallocated_payment": { "$ref": "#/components/schemas/PurchasePaymentFields/properties/unallocated_payment" } }, "allOf": [ { "if": { "required": [ "channel" ], "properties": { "channel": { "const": "loan_financing" } } }, "then": { "not": { "required": [ "day_order" ] } } }, { "if": { "properties": { "channel": { "const": "owner_private" } }, "required": [ "channel" ] }, "then": { "required": [ "private_currency_code" ], "not": { "anyOf": [ { "required": [ "ledger_account_public_id" ] }, { "required": [ "payer_contact_public_id" ] }, { "required": [ "receiving_administration_public_id" ] } ] }, "properties": { "route_configuration_public_ids": { "maxItems": 0 }, "edge_amounts": { "maxItems": 0 } } }, "else": { "not": { "anyOf": [ { "required": [ "private_currency_code" ] } ] } } }, { "oneOf": [ { "properties": { "unallocated_payment": { "const": true }, "allocations": { "maxItems": 0 }, "difference_treatment": { "const": "hold_supplier_credit" }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" } }, "required": [ "unallocated_payment", "supplier_public_id" ] }, { "properties": { "unallocated_payment": { "const": false }, "allocations": { "minItems": 1 } } } ] } ] }, "PurchaseCreateSupplierRefundFields": { "type": "object", "additionalProperties": false, "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/supplier_credit_public_id" }, "channel": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/channel" }, "receiving_administration_public_id": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/receiving_administration_public_id" }, "ledger_account_public_id": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/ledger_account_public_id" }, "payer_contact_public_id": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/payer_contact_public_id" }, "refund_date": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/refund_date" }, "amount": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/amount" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/credit_currency_amount" }, "fx": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/fx" }, "route_configuration_public_ids": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/route_configuration_public_ids" }, "edge_amounts": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/edge_amounts" }, "state_hash": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/state_hash" }, "expected_revision": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/expected_revision" }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." }, "private_currency_code": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/private_currency_code" }, "private_funding_allocations": { "$ref": "#/components/schemas/PurchaseSupplierRefundFields/properties/private_funding_allocations" }, "opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "payroll_source_key": { "$ref": "#/components/schemas/PayrollRefundSourceKey" } }, "allOf": [ { "if": { "properties": { "channel": { "const": "owner_private" } }, "required": [ "channel" ] }, "then": { "required": [ "private_currency_code", "private_funding_allocations" ], "not": { "anyOf": [ { "required": [ "ledger_account_public_id" ] }, { "required": [ "payer_contact_public_id" ] }, { "required": [ "receiving_administration_public_id" ] } ] }, "properties": { "route_configuration_public_ids": { "maxItems": 0 }, "edge_amounts": { "maxItems": 0 } } }, "else": { "not": { "anyOf": [ { "required": [ "private_currency_code" ] }, { "required": [ "private_funding_allocations" ] } ] } } } ] }, "PreviewPurchaseSettlementRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseCreateSettlementFields" }, { "type": "object", "required": [ "channel", "payment_date", "amount", "allocations" ] } ], "unevaluatedProperties": false, "description": "Supplier remains required for ordinary purchase payments. A payroll tax payment identifies the beneficiary through its tax source without a fabricated contact." }, "PostPurchaseSettlementRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseCreateSettlementFields" }, { "type": "object", "required": [ "channel", "payment_date", "amount", "allocations", "state_hash" ] } ], "unevaluatedProperties": false, "description": "Supplier remains required for ordinary purchase payments. A payroll tax payment identifies the beneficiary through its tax source without a fabricated contact." }, "PreviewUpdatePurchaseSettlementRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchasePaymentFields" }, { "type": "object", "required": [ "channel", "payment_date", "amount", "allocations", "expected_revision" ] } ], "unevaluatedProperties": false, "description": "Supplier remains required for ordinary purchase payments. A payroll tax payment identifies the beneficiary through its tax source without a fabricated contact." }, "UpdatePurchaseSettlementRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchasePaymentFields" }, { "type": "object", "required": [ "channel", "payment_date", "amount", "allocations", "state_hash", "expected_revision" ] } ], "unevaluatedProperties": false, "description": "Supplier remains required for ordinary purchase payments. A payroll tax payment identifies the beneficiary through its tax source without a fabricated contact." }, "DeletePurchaseSourceRequest": { "type": "object", "required": [ "expected_revision", "state_hash" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash", "description": "For documents use delete_preview.state_hash from the current GET response, including dependent manual VAT revisions. Under the active periodic cash policy, local bank/cash payment and refund deletion uses state_hash from the settlement delete-preview endpoint, including all existing valuation adjustments. Other settlements retain their ordinary state_hash." } } }, "PurchaseSupplierRefundFields": { "type": "object", "additionalProperties": false, "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration", "owner_private" ] }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Required only for current-account settlements: the explicitly selected existing contact of the own or a linked administration, independently of the supplier. The complete configured route and current write access to every involved administration are required." }, "refund_date": { "type": "string", "format": "date" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "fx": { "$ref": "#/components/schemas/PurchasePaymentFxInput" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/PurchaseRouteEdgeAmountInput" } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 }, "private_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Required only for owner_private: the actual payment currency. No business bank or cash account is created." }, "private_funding_allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePrivateFundingInput" }, "minItems": 1, "maxItems": 100, "description": "Explicit portion returned from each original owner-private payment, in that original payment currency. Bounds apply to original funding, not to actual current EUR proceeds." }, "opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "payroll_source_key": { "$ref": "#/components/schemas/PayrollRefundSourceKey" } }, "allOf": [ { "if": { "properties": { "channel": { "const": "owner_private" } }, "required": [ "channel" ] }, "then": { "required": [ "private_currency_code", "private_funding_allocations" ], "not": { "anyOf": [ { "required": [ "ledger_account_public_id" ] }, { "required": [ "payer_contact_public_id" ] }, { "required": [ "receiving_administration_public_id" ] } ] }, "properties": { "route_configuration_public_ids": { "maxItems": 0 }, "edge_amounts": { "maxItems": 0 } } }, "else": { "not": { "anyOf": [ { "required": [ "private_currency_code" ] }, { "required": [ "private_funding_allocations" ] } ] } } } ] }, "PreviewSupplierRefundRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseCreateSupplierRefundFields" }, { "type": "object", "required": [ "channel", "refund_date", "amount" ], "oneOf": [ { "required": [ "supplier_credit_public_id" ], "not": { "anyOf": [ { "required": [ "opening_item_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "opening_item_public_id" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "payroll_source_key" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "opening_item_public_id" ] } ] } } ] } ], "unevaluatedProperties": false }, "PostSupplierRefundRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseCreateSupplierRefundFields" }, { "type": "object", "required": [ "channel", "refund_date", "amount", "state_hash" ], "oneOf": [ { "required": [ "supplier_credit_public_id" ], "not": { "anyOf": [ { "required": [ "opening_item_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "opening_item_public_id" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "payroll_source_key" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "opening_item_public_id" ] } ] } } ] } ], "unevaluatedProperties": false }, "PreviewUpdateSupplierRefundRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseSupplierRefundFields" }, { "type": "object", "required": [ "channel", "refund_date", "amount", "expected_revision" ], "oneOf": [ { "required": [ "supplier_credit_public_id" ], "not": { "anyOf": [ { "required": [ "opening_item_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "opening_item_public_id" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "payroll_source_key" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "opening_item_public_id" ] } ] } } ] } ], "unevaluatedProperties": false }, "UpdateSupplierRefundRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseSupplierRefundFields" }, { "type": "object", "required": [ "channel", "refund_date", "amount", "state_hash", "expected_revision" ], "oneOf": [ { "required": [ "supplier_credit_public_id" ], "not": { "anyOf": [ { "required": [ "opening_item_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "opening_item_public_id" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "payroll_source_key" ] } ] } }, { "required": [ "payroll_source_key" ], "not": { "anyOf": [ { "required": [ "supplier_credit_public_id" ] }, { "required": [ "opening_item_public_id" ] } ] } } ] } ], "unevaluatedProperties": false }, "PurchaseSupplierCreditApplicationFields": { "type": "object", "additionalProperties": false, "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "application_date": { "type": "string", "format": "date" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "document_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "fx": { "type": "object", "required": [ "rate", "source", "observed_at" ], "additionalProperties": false, "properties": { "rate": { "$ref": "#/components/schemas/PurchaseDecimal" }, "source": { "type": "string", "maxLength": 80 }, "observed_at": { "type": "string", "format": "date-time" } } }, "allocations": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchasePayableAllocationInput" } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "PreviewSupplierCreditApplicationRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseSupplierCreditApplicationFields" }, { "type": "object", "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "document_currency_amount", "allocations" ] } ], "unevaluatedProperties": false }, "PostSupplierCreditApplicationRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseSupplierCreditApplicationFields" }, { "type": "object", "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "document_currency_amount", "allocations", "state_hash" ] } ], "unevaluatedProperties": false }, "PreviewUpdateSupplierCreditApplicationRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseSupplierCreditApplicationFields" }, { "type": "object", "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "document_currency_amount", "allocations", "expected_revision" ] } ], "unevaluatedProperties": false }, "UpdateSupplierCreditApplicationRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseSupplierCreditApplicationFields" }, { "type": "object", "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "document_currency_amount", "allocations", "state_hash", "expected_revision" ] } ], "unevaluatedProperties": false }, "PurchaseVatCorrectionFields": { "type": "object", "additionalProperties": false, "properties": { "correction_type": { "type": "string", "enum": [ "one_year_due", "confirmed_unpayable" ] }, "correction_date": { "type": "string", "format": "date" }, "basis_due_date": { "type": "string", "format": "date" }, "reason": { "type": "string", "minLength": 1, "maxLength": 255 }, "document_public_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" } } }, "PreviewPurchaseVatCorrectionRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseVatCorrectionFields" }, { "type": "object", "required": [ "correction_type", "correction_date", "basis_due_date", "reason", "document_public_ids" ] } ], "unevaluatedProperties": false }, "PostPurchaseVatCorrectionRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseVatCorrectionFields" }, { "type": "object", "required": [ "correction_type", "correction_date", "basis_due_date", "reason", "document_public_ids", "state_hash" ] } ], "unevaluatedProperties": false }, "PostPurchaseVatRenewalRequest": { "type": "object", "required": [ "original_correction_public_id", "correction_date", "reason", "state_hash" ], "additionalProperties": false, "properties": { "original_correction_public_id": { "$ref": "#/components/schemas/Ulid" }, "correction_date": { "type": "string", "format": "date" }, "reason": { "type": "string", "minLength": 1, "maxLength": 255 }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" } } }, "PreviewPurchaseVatRenewalRequest": { "type": "object", "required": [ "original_correction_public_id", "correction_date", "reason" ], "additionalProperties": false, "properties": { "original_correction_public_id": { "$ref": "#/components/schemas/Ulid" }, "correction_date": { "type": "string", "format": "date" }, "reason": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "PurchaseVatCorrectionPreviewLine": { "type": "object", "required": [ "document_public_id", "document_number", "source_purchase_document_line_public_id", "line_number", "native_unpaid_amount", "native_vat_amount", "base_vat_amount" ], "additionalProperties": false, "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_number": { "type": "string" }, "source_purchase_document_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_number": { "type": "integer", "minimum": 1 }, "native_unpaid_amount": { "type": "string" }, "native_vat_amount": { "type": "string" }, "base_vat_amount": { "type": "string" } } }, "PurchaseVatCorrectionPreview": { "type": "object", "required": [ "state_hash", "correction_type", "supplier", "correction_date", "basis_due_date", "reason", "reverses_correction_public_id", "lines", "journals" ], "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "correction_type": { "type": "string", "enum": [ "one_year_due", "confirmed_unpayable", "renewed_deduction" ] }, "supplier": { "$ref": "#/components/schemas/PurchaseParty" }, "correction_date": { "type": "string", "format": "date" }, "basis_due_date": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "reverses_correction_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PurchaseVatCorrectionPreviewLine" } }, "journals": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/PurchasePreviewJournal" } } } }, "PurchaseVatCorrectionPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseVatCorrectionPreview" } } }, "PurchaseParty": { "type": "object", "required": [ "public_id", "display_name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "display_name": { "type": "string" } } }, "PurchaseJournalIdentity": { "type": "object", "required": [ "position", "public_id", "number", "status" ], "additionalProperties": false, "properties": { "position": { "type": "string" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string", "pattern": "^J[0-9]{6}$" }, "status": { "type": "string", "enum": [ "posted", "deleted" ] } } }, "PurchaseDocumentLine": { "type": "object", "required": [ "public_id", "line_number", "description", "ledger_account", "vat_treatment_code", "native_net_amount", "native_vat_amount", "native_gross_amount", "deductible_percentage", "margin_method" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "line_number": { "type": "integer", "minimum": 1 }, "description": { "type": "string" }, "ledger_account": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "vat_treatment_code": { "type": [ "string", "null" ] }, "native_net_amount": { "type": "string" }, "native_vat_amount": { "type": "string" }, "native_gross_amount": { "type": "string" }, "deductible_percentage": { "type": "string" }, "margin_method": { "type": "string", "enum": [ "none", "global_9", "global_21" ] }, "cost_period": { "$ref": "#/components/schemas/PurchaseCostPeriod" } } }, "PurchaseDocument": { "type": "object", "required": [ "public_id", "number", "document_type", "supplier", "supplier_vat_identification_number", "external_number", "document_date", "performance_date", "due_date", "description", "currency_code", "base_currency_code", "native_net_amount", "native_vat_amount", "native_gross_amount", "base_net_amount", "base_vat_amount", "base_gross_amount", "open_amount", "status", "lines", "settlements", "journal_entries", "state_hash", "revision", "deleted_at", "deleted_by", "delete_preview" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string", "pattern": "^I[0-9]{6}$" }, "document_type": { "type": "string", "enum": [ "purchase", "supplier_credit_note", "salary", "payroll_tax_return" ] }, "supplier": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseParty" }, { "type": "null" } ] }, "supplier_vat_identification_number": { "type": [ "string", "null" ] }, "external_number": { "type": [ "string", "null" ] }, "document_date": { "type": [ "string", "null" ], "format": "date" }, "performance_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "currency_code": { "type": [ "string", "null" ] }, "base_currency_code": { "type": [ "string", "null" ] }, "native_net_amount": { "type": [ "string", "null" ] }, "native_vat_amount": { "type": [ "string", "null" ] }, "native_gross_amount": { "type": [ "string", "null" ] }, "base_net_amount": { "type": [ "string", "null" ] }, "base_vat_amount": { "type": [ "string", "null" ] }, "base_gross_amount": { "type": [ "string", "null" ] }, "open_amount": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "partially_paid", "paid", "supplier_credit", "deleted" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseDocumentLine" } }, "settlements": { "type": "array", "items": { "type": "object", "required": [ "public_id", "settlement_date", "native_document_amount", "status" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_date": { "type": [ "string", "null" ], "format": "date" }, "native_document_amount": { "type": "string" }, "status": { "type": "string", "enum": [ "posted", "deleted" ] } } } }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseJournalIdentity" } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "revision": { "type": "integer", "minimum": 1 }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "oneOf": [ { "type": "object", "required": [ "public_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "type": "null" } ] }, "delete_preview": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "state_hash", "vat_revisions" ], "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "vat_revisions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "occurred_on", "amount", "reason" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "occurred_on": { "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "reason": { "type": "string" } } } }, "fixed_assets": { "type": "object", "additionalProperties": false, "required": [ "has_assets", "state_hash", "corrections", "errors" ], "properties": { "has_assets": { "type": "boolean" }, "state_hash": { "type": [ "string", "null" ] }, "corrections": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "string" } } } } } }, { "type": "null" } ] }, "payroll": { "oneOf": [ { "$ref": "#/components/schemas/PurchasePayrollData" }, { "type": "null" } ] }, "annual_allocation": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseAnnualCostAllocation" } } } }, "PurchaseDocumentResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseDocument" } } }, "PurchaseDocumentCollection": { "type": "object", "required": [ "data", "links" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseDocument" } }, "links": { "type": "object", "required": [ "next" ], "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ] } } } } }, "PurchaseSettlement": { "type": "object", "required": [ "public_id", "settlement_type", "supplier", "channel", "settlement_account", "payer", "settlement_date", "currency_code", "base_currency_code", "native_amount", "base_amount", "document_currency_code", "document_currency_amount", "allocations", "supplier_credit", "route", "journal_entries", "state_hash", "revision", "status", "deleted_at", "deleted_by", "application_input", "loan_public_id", "private_funding_allocations", "private_refund_funding", "private_funding_evidence" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "settlement_type": { "type": "string", "enum": [ "payment", "supplier_refund", "supplier_credit_application", "advance_application", "supplier_credit_writeoff" ] }, "supplier": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseParty" }, { "type": "null" } ] }, "channel": { "type": [ "string", "null" ] }, "settlement_account": { "oneOf": [ { "type": "object", "required": [ "public_id", "code" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" } } }, { "type": "null" } ] }, "payer": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseParty" }, { "type": "null" } ] }, "settlement_date": { "type": [ "string", "null" ], "format": "date" }, "currency_code": { "type": [ "string", "null" ] }, "base_currency_code": { "type": [ "string", "null" ] }, "native_amount": { "type": [ "string", "null" ] }, "base_amount": { "type": [ "string", "null" ] }, "document_currency_code": { "type": [ "string", "null" ], "description": "Original payment valuation currency; null for refunds, credit applications and deleted settlements." }, "document_currency_amount": { "type": [ "string", "null" ], "description": "Original payment value in document currency, before allocation and payment-difference treatment." }, "allocations": { "type": "array", "items": { "type": "object", "required": [ "document_public_id", "document_number", "native_document_amount", "base_carrying_amount", "base_fx_result_amount" ], "additionalProperties": false, "properties": { "document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "document_number": { "type": [ "string", "null" ] }, "native_document_amount": { "type": "string" }, "base_carrying_amount": { "type": "string" }, "base_fx_result_amount": { "type": "string" }, "opening_item_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } } } }, "supplier_credit": { "oneOf": [ { "type": "object", "required": [ "public_id", "usage_type", "native_amount", "base_carrying_amount" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "usage_type": { "type": "string", "enum": [ "advance_application", "credit_application", "supplier_refund", "credit_writeoff" ] }, "native_amount": { "type": "string" }, "base_carrying_amount": { "type": "string" } } }, { "type": "null" } ] }, "route": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseRouteSnapshot" }, { "type": "null" } ] }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseJournalIdentity" } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "posted", "deleted" ] }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "oneOf": [ { "type": "object", "required": [ "public_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "type": "null" } ] }, "application_input": { "description": "Exact input for independent supplier-credit applications; for loan_financing payments only loan_public_id. Null for legacy applications and remaining settlement channels. Deleted sources clear financial input.", "oneOf": [ { "type": "object", "required": [ "loan_public_id" ], "additionalProperties": false, "properties": { "loan_public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "type": "object", "required": [ "supplier_credit_public_id", "application_date", "credit_currency_amount", "document_currency_amount", "allocations" ], "additionalProperties": false, "properties": { "supplier_credit_public_id": { "$ref": "#/components/schemas/Ulid" }, "application_date": { "type": "string", "format": "date" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "document_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "fx": { "oneOf": [ { "type": "object", "required": [ "rate", "source", "observed_at" ], "additionalProperties": false, "properties": { "rate": { "$ref": "#/components/schemas/PurchaseDecimal" }, "source": { "type": "string", "maxLength": 80 }, "observed_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] }, "allocations": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PurchasePayableAllocationInput" } } } }, { "type": "null" }, { "$ref": "#/components/schemas/PurchaseSupplierCreditWriteoffFields" } ] }, "loan_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Linked financing loan; null for other channels or deleted settlements." }, "private_funding_allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePrivateFundingInput" } }, "private_refund_funding": { "type": "array", "items": { "type": "object", "required": [ "refund_public_id", "native_funding_amount", "historical_base_amount", "claim_amount", "claim_currency_code", "funding_basis" ], "additionalProperties": false, "properties": { "refund_public_id": { "$ref": "#/components/schemas/Ulid" }, "native_funding_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "historical_base_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "claim_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "claim_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "funding_basis": { "type": "string", "enum": [ "document", "supplier_credit" ] } } } }, "private_funding_evidence": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePrivateFundingEvidence" } }, "unallocated_payment": { "type": "boolean" }, "payroll_refund": { "$ref": "#/components/schemas/PayrollRefundOrigin" } } }, "PurchaseSettlementResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseSettlement" } } }, "PurchaseSettlementCollection": { "type": "object", "required": [ "data", "links" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseSettlement" } }, "links": { "type": "object", "required": [ "next" ], "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ] } } } } }, "PurchasePreviewJournalLine": { "type": "object", "required": [ "ledger_account", "side", "amount" ], "additionalProperties": false, "properties": { "ledger_account": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string" }, "native_currency_code": { "type": [ "string", "null" ], "description": "Original currency of a monetary line, when present." }, "native_amount": { "type": [ "string", "null" ], "description": "Exact original foreign-currency amount, when present." }, "exact_amount": { "type": "boolean", "description": "Show the exact stored amount when the document has proved component conversion rounding." } } }, "PurchasePreviewJournal": { "type": "object", "required": [ "position", "date", "lines" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "position": { "enum": [ "periodic_valuation", "vat_revision" ] } }, "required": [ "position" ] }, "then": { "type": "object" }, "else": { "properties": { "lines": { "anyOf": [ { "maxItems": 0 }, { "minItems": 2 } ] } } } } ], "properties": { "before": { "$ref": "#/components/schemas/CurrencyExchangeJournal", "description": "Original physical valuation journal before replacing its existing lines." }, "before_label": { "type": "string" }, "after_label": { "type": "string" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "entry_number": { "type": "string" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "position": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePreviewJournalLine" } }, "heading": { "type": "string" }, "administration_name": { "type": "string" }, "currency_code": { "type": "string" }, "scheduled": { "type": "boolean" } } }, "PurchaseDuplicateWarning": { "type": "object", "required": [ "public_id", "number", "reason" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "reason": { "type": "string", "enum": [ "supplier_external_number", "supplier_date_currency_amount" ] } } }, "PurchaseRouteSnapshot": { "type": "object", "required": [ "state_hash", "hops", "usage_mode", "configuration_public_ids", "nodes", "edges" ], "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "hops": { "type": "integer", "minimum": 1 }, "usage_mode": { "type": "string", "enum": [ "normal", "settlement_only" ] }, "configuration_public_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" } }, "nodes": { "type": "array", "items": { "type": "object", "required": [ "type", "public_id", "name" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "administration", "contact" ] }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" } } } }, "edges": { "type": "array", "items": { "type": "object", "required": [ "sequence", "configuration_public_id", "denomination_currency_code", "from_administration_public_id", "to_type", "to_public_id" ], "additionalProperties": false, "properties": { "sequence": { "type": "integer" }, "configuration_public_id": { "$ref": "#/components/schemas/Ulid" }, "denomination_currency_code": { "type": "string" }, "from_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "to_type": { "type": "string", "enum": [ "administration", "contact" ] }, "to_public_id": { "$ref": "#/components/schemas/Ulid" } } } }, "edge_amounts": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseRouteEdgeAmountInput" } } } }, "PurchasePreview": { "type": "object", "required": [ "state_hash", "document_type", "supplier", "document_date", "performance_date", "currency_code", "totals", "duplicate_warning", "requires_duplicate_acknowledgement", "journals", "payment" ], "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "document_state_hash": { "$ref": "#/components/schemas/PurchaseStateHash", "description": "Original document calculation binding when a payment is included in the joint preview." }, "document_type": { "type": "string" }, "supplier": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseParty" }, { "type": "null" } ] }, "document_date": { "type": "string", "format": "date" }, "performance_date": { "type": [ "string", "null" ], "format": "date" }, "currency_code": { "type": "string" }, "totals": { "type": "object", "required": [ "native_net_amount", "native_vat_amount", "native_gross_amount", "base_net_amount", "base_vat_amount", "base_gross_amount" ], "additionalProperties": false, "properties": { "native_net_amount": { "type": [ "string", "null" ] }, "native_vat_amount": { "type": [ "string", "null" ] }, "native_gross_amount": { "type": [ "string", "null" ] }, "base_net_amount": { "type": [ "string", "null" ] }, "base_vat_amount": { "type": [ "string", "null" ] }, "base_gross_amount": { "type": [ "string", "null" ] } } }, "duplicate_warning": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseDuplicateWarning" }, { "type": "null" } ] }, "requires_duplicate_acknowledgement": { "type": "boolean" }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePreviewJournal" } }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseSettlementPreview" }, { "type": "null" } ] }, "vat_revisions": { "type": "object", "additionalProperties": false, "required": [ "required", "corrections" ], "properties": { "required": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "fact_public_id", "line_public_id", "occurred_on", "current_amount", "reason" ], "properties": { "fact_public_id": { "$ref": "#/components/schemas/Ulid" }, "line_public_id": { "$ref": "#/components/schemas/Ulid" }, "occurred_on": { "type": "string", "format": "date" }, "current_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "reason": { "type": "string" } } } }, "corrections": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "contract_version", "fact_type", "occurred_on", "reason", "taxable_amount", "vat_amount", "ledger_account_public_id", "purchase_document_line_public_id", "sales_document_public_id", "effects", "journal_lines", "facts" ], "properties": { "contract_version": { "type": "integer", "const": 1 }, "fact_type": { "type": "string", "const": "purchase_revision" }, "occurred_on": { "type": "string", "format": "date" }, "reason": { "type": "string" }, "taxable_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "vat_amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "purchase_document_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "sales_document_public_id": { "type": "null" }, "effects": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "rubric_code", "component", "amount" ], "properties": { "rubric_code": { "type": "string", "const": "5b" }, "component": { "type": "string", "const": "deductible" }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "journal_lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "ledger_account_public_id", "account_label", "side", "amount" ], "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "account_label": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,4})?$" } } } }, "facts": { "type": "object", "additionalProperties": true }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" }, "entry_number": { "type": "string", "pattern": "^J[0-9]{6}$" }, "revision": { "type": "integer", "minimum": 1 }, "operation": { "type": "string", "enum": [ "update", "remove" ] } }, "description": "In-place update or removal of the same manual VAT revision and original journal identity; no reversal or replacement journal is created." } } } }, "fixed_assets": { "$ref": "#/components/schemas/FixedAssetPurchaseCorrection" }, "payable_amount": { "type": "string", "description": "Actual payroll debt, distinct from absent invoice totals." }, "payroll_balance": { "type": "object", "additionalProperties": false, "required": [ "has_payments", "currency_code", "preserved_paid", "counted_paid", "remaining" ], "properties": { "has_payments": { "type": "boolean" }, "currency_code": { "type": "string" }, "preserved_paid": { "type": "string" }, "counted_paid": { "type": "string" }, "remaining": { "type": "string" }, "returned": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "counted_returned": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{4}$" } } }, "conversion_rounding": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "contract", "rounding_amount", "rounding_side", "ledger_account_public_id" ], "properties": { "contract": { "const": "purchase-component-conversion-rounding-v1" }, "rounding_amount": { "type": "string", "pattern": "^\\d+\\.\\d{4}$" }, "rounding_side": { "enum": [ "debit", "credit" ] }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" } } } ] }, "annual_allocation": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseAnnualCostAllocation" } }, "annual_release_schedule": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePreviewJournal" } } } }, "PurchaseSettlementPreviewAllocation": { "type": "object", "required": [ "document_public_id", "native_document_amount", "base_carrying_amount", "base_fx_result_amount" ], "additionalProperties": false, "properties": { "document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "native_document_amount": { "type": "string" }, "base_carrying_amount": { "type": "string" }, "base_fx_result_amount": { "type": "string" }, "opening_item_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } } }, "PurchaseSettlementPreviewCredit": { "type": "object", "required": [ "native_amount", "base_amount", "native_remaining_amount", "base_remaining_amount", "usages" ], "additionalProperties": false, "properties": { "native_amount": { "type": "string" }, "base_amount": { "type": "string" }, "native_remaining_amount": { "type": "string" }, "base_remaining_amount": { "type": "string" }, "usages": { "type": "array", "items": { "type": "object", "required": [ "document_public_id", "native_amount", "base_carrying_amount" ], "additionalProperties": false, "properties": { "document_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "native_amount": { "type": "string" }, "base_carrying_amount": { "type": "string" } } } } } }, "PurchaseSettlementPreview": { "type": "object", "required": [ "state_hash", "settlement_type", "supplier", "payment_date", "payment_currency_code", "payment_amount", "base_amount", "allocations", "supplier_credit", "route", "journals", "loan_public_id" ], "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "settlement_type": { "type": "string" }, "supplier": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseParty" }, { "type": "null" } ] }, "payment_date": { "type": "string", "format": "date" }, "payment_currency_code": { "type": "string" }, "payment_amount": { "type": "string" }, "base_amount": { "type": "string" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseSettlementPreviewAllocation" } }, "supplier_credit": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseSettlementPreviewCredit" }, { "type": "null" } ] }, "route": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseRouteSnapshot" }, { "type": "null" } ] }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePreviewJournal" } }, "loan_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Linked financing loan; null for other channels or deleted settlements." }, "private_funding_updates": { "type": "array", "items": { "type": "object", "required": [ "refund_public_id", "native_funding_amount", "historical_base_before", "historical_base_after" ], "additionalProperties": false, "properties": { "refund_public_id": { "$ref": "#/components/schemas/Ulid" }, "native_funding_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "historical_base_before": { "$ref": "#/components/schemas/PurchaseDecimal" }, "historical_base_after": { "$ref": "#/components/schemas/PurchaseDecimal" } } } }, "private_funding_evidence": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePrivateFundingEvidence" } } } }, "SupplierCreditCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "public_id", "supplier", "currency_code", "native_amount", "native_remaining_amount", "base_remaining_amount", "state_hash", "revision" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "supplier": { "$ref": "#/components/schemas/PurchaseParty" }, "currency_code": { "type": "string" }, "native_amount": { "type": "string" }, "native_remaining_amount": { "type": "string" }, "base_remaining_amount": { "type": "string" }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "revision": { "type": "integer" } } } } } }, "PurchaseOpenItem": { "type": "object", "required": [ "public_id", "number", "supplier", "document_date", "due_date", "currency_code", "gross_amount", "open_amount" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "supplier": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseParty" }, { "type": "null" } ] }, "document_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "currency_code": { "type": "string" }, "gross_amount": { "type": "string" }, "open_amount": { "type": "string" }, "basis": { "type": "string", "enum": [ "due_date", "document_date_reminder_only" ] } } }, "PurchaseOpenItemCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOpenItem" } } } }, "PurchaseReconciliationResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "currency_code", "subledger_open_amount", "trade_payables_balance", "difference", "matches", "opening_balance", "expected_balance", "has_unspecified_opening_balance" ], "additionalProperties": false, "properties": { "currency_code": { "type": "string" }, "subledger_open_amount": { "type": "string" }, "identified_open_items_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "description": "Ordinary open purchase documents plus currently outstanding specified trade opening items; excludes an unspecified opening total." }, "trade_payables_balance": { "type": "string" }, "difference": { "type": "string" }, "matches": { "type": "boolean" }, "opening_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "description": "Signed balance brought forward, to be specified separately." }, "opening_specification": { "oneOf": [ { "$ref": "#/components/schemas/OpeningTradeSpecification" }, { "type": "null" } ] }, "expected_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "description": "Recorded open items plus the opening balance, each counted once." }, "has_unspecified_opening_balance": { "type": "boolean", "description": "True when an opening total still lacks individual invoice specifications; a matching ledger is not proof of complete invoice coverage." }, "payroll": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "account_public_id", "code", "name", "subledger_open_amount", "opening_balance", "balance", "difference", "matches" ], "properties": { "account_public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "subledger_open_amount": { "type": "string" }, "opening_balance": { "type": "string" }, "balance": { "type": "string" }, "difference": { "type": "string" }, "matches": { "type": "boolean" } } } } } } } }, "PurchasePublicOption": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "currency_code": { "type": "string" } } }, "PurchaseOptionsResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "suppliers", "line_accounts", "settlement_accounts", "vat_treatments", "loans" ], "additionalProperties": false, "properties": { "suppliers": { "type": "array", "items": { "type": "object", "required": [ "public_id", "number", "display_name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "integer" }, "display_name": { "type": "string" } } } }, "line_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePublicOption" } }, "settlement_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePublicOption" } }, "vat_treatments": { "type": "array", "items": { "type": "object", "required": [ "code", "label", "display_group", "mechanism" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "display_group": { "type": "string" }, "mechanism": { "type": "string" } } } }, "loans": { "type": "array", "description": "Eligible borrowed loans; empty unless the token has loans:write and the user can manage loans.", "items": { "type": "object", "required": [ "public_id", "name", "currency_code" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "currency_code": { "type": "string" } } } } } } } }, "PurchaseMapping": { "oneOf": [ { "type": "object", "required": [ "public_id", "code", "name", "revision" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" }, "revision": { "type": "integer" } } }, { "type": "null" } ] }, "PurchaseAccountMappingData": { "type": "object", "required": [ "trade_payables", "supplier_credits_receivable", "payment_difference_gain", "payment_difference_loss", "prepaid_purchase_clearing", "accrued_purchase_clearing", "private_contributions", "private_withdrawals", "net_salary_payable", "payroll_taxes_payable", "holiday_payable" ], "additionalProperties": false, "properties": { "trade_payables": { "$ref": "#/components/schemas/PurchaseMapping" }, "supplier_credits_receivable": { "$ref": "#/components/schemas/PurchaseMapping" }, "payment_difference_gain": { "$ref": "#/components/schemas/PurchaseMapping" }, "payment_difference_loss": { "$ref": "#/components/schemas/PurchaseMapping" }, "prepaid_purchase_clearing": { "$ref": "#/components/schemas/PurchaseMapping" }, "accrued_purchase_clearing": { "$ref": "#/components/schemas/PurchaseMapping" }, "private_contributions": { "$ref": "#/components/schemas/PurchaseMapping" }, "private_withdrawals": { "$ref": "#/components/schemas/PurchaseMapping" }, "net_salary_payable": { "$ref": "#/components/schemas/PurchaseMapping" }, "payroll_taxes_payable": { "$ref": "#/components/schemas/PurchaseMapping" }, "holiday_payable": { "$ref": "#/components/schemas/PurchaseMapping" } } }, "PurchaseAccountMappingsResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseAccountMappingData" } } }, "PutPurchaseAccountMappingsRequest": { "type": "object", "required": [ "trade_payables", "supplier_credits_receivable", "payment_difference_gain", "payment_difference_loss", "prepaid_purchase_clearing", "accrued_purchase_clearing" ], "additionalProperties": false, "properties": { "trade_payables": { "$ref": "#/components/schemas/Ulid" }, "supplier_credits_receivable": { "$ref": "#/components/schemas/Ulid" }, "payment_difference_gain": { "$ref": "#/components/schemas/Ulid" }, "payment_difference_loss": { "$ref": "#/components/schemas/Ulid" }, "prepaid_purchase_clearing": { "$ref": "#/components/schemas/Ulid" }, "accrued_purchase_clearing": { "$ref": "#/components/schemas/Ulid" }, "private_contributions": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Optional explicitly configured capital mapping, only for a sole proprietorship. Omitting it leaves the mapping unchanged." }, "private_withdrawals": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Optional explicitly configured capital mapping, only for a sole proprietorship. Omitting it leaves the mapping unchanged." }, "net_salary_payable": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "payroll_taxes_payable": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "holiday_payable": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } } }, "PurchaseVatCorrection": { "type": "object", "required": [ "public_id", "correction_type", "supplier", "correction_date", "basis_due_date", "reason", "reverses_correction_public_id", "lines", "journal_entries", "state_hash", "revision", "status", "deleted_at", "deleted_by" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "correction_type": { "type": "string", "enum": [ "one_year_due", "confirmed_unpayable", "renewed_deduction" ] }, "supplier": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseParty" }, { "type": "null" } ] }, "correction_date": { "type": [ "string", "null" ], "format": "date" }, "basis_due_date": { "type": [ "string", "null" ], "format": "date" }, "reason": { "type": [ "string", "null" ] }, "reverses_correction_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "required": [ "document_public_id", "document_number", "line_number", "native_unpaid_amount", "native_vat_amount", "base_vat_amount" ], "additionalProperties": false, "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_number": { "type": "string" }, "line_number": { "type": "integer" }, "native_unpaid_amount": { "type": "string" }, "native_vat_amount": { "type": "string" }, "base_vat_amount": { "type": "string" } } } }, "journal_entries": { "type": "array", "items": { "type": "object", "required": [ "public_id", "number", "status" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "status": { "type": "string" } } } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "revision": { "type": "integer" }, "status": { "type": "string", "enum": [ "posted", "deleted" ] }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "oneOf": [ { "type": "object", "required": [ "public_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" } } }, { "type": "null" } ] } } }, "PurchaseVatCorrectionResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseVatCorrection" } } }, "PurchaseVatCorrectionCollection": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseVatCorrection" } } } }, "ContactFinancialPosition": { "type": "object", "required": [ "currency_code", "customer_receivable", "supplier_payable", "customer_credit", "supplier_credit", "net_indication" ], "additionalProperties": false, "properties": { "currency_code": { "type": "string" }, "customer_receivable": { "type": "string" }, "supplier_payable": { "type": "string" }, "customer_credit": { "type": "string" }, "supplier_credit": { "type": "string" }, "net_indication": { "type": "string" } } }, "ContactFinancialDocumentItem": { "type": "object", "required": [ "public_id", "date", "type", "currency_code", "amount" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" }, "date": { "type": [ "string", "null" ], "format": "date" }, "type": { "type": "string" }, "currency_code": { "type": "string" }, "amount": { "type": "string" }, "open_amount": { "type": "string" } } }, "ContactFinancialSettlementItem": { "type": "object", "required": [ "public_id", "type", "date", "currency_code", "amount" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "type": { "type": "string" }, "date": { "type": [ "string", "null" ], "format": "date" }, "currency_code": { "type": "string" }, "amount": { "type": "string" } } }, "ContactSupplierCreditItem": { "type": "object", "required": [ "public_id", "currency_code", "remaining_amount" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string" }, "remaining_amount": { "type": "string" } } }, "ContactCurrentAccountMovementItem": { "type": "object", "required": [ "public_id", "date", "currency_code", "amount", "direction" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "date": { "type": [ "string", "null" ], "format": "date" }, "currency_code": { "type": "string" }, "amount": { "type": "string" }, "direction": { "type": "string" } } }, "ContactFinancialOverviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "contact", "positions", "sales_documents", "purchase_documents", "sales_settlements", "purchase_settlements", "supplier_credits", "current_account_movements", "opening_items" ], "additionalProperties": false, "properties": { "contact": { "$ref": "#/components/schemas/PurchaseParty" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/ContactFinancialPosition" } }, "sales_documents": { "type": "array", "items": { "$ref": "#/components/schemas/ContactFinancialDocumentItem" } }, "purchase_documents": { "type": "array", "items": { "$ref": "#/components/schemas/ContactFinancialDocumentItem" } }, "sales_settlements": { "type": "array", "items": { "$ref": "#/components/schemas/ContactFinancialSettlementItem" } }, "purchase_settlements": { "type": "array", "items": { "$ref": "#/components/schemas/ContactFinancialSettlementItem" } }, "supplier_credits": { "type": "array", "items": { "$ref": "#/components/schemas/ContactSupplierCreditItem" } }, "current_account_movements": { "type": "array", "items": { "$ref": "#/components/schemas/ContactCurrentAccountMovementItem" } }, "opening_items": { "type": "array", "items": { "$ref": "#/components/schemas/ContactOpeningItem" } } } } } }, "ErrorEnvelope": { "type": "object", "required": [ "error", "request_id" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "request_id": { "$ref": "#/components/schemas/Ulid" } } }, "FreshSharesSettlementInput": { "type": "object", "required": [ "settlement_date", "cash_account_public_id", "amount" ], "properties": { "settlement_date": { "type": "string", "format": "date" }, "cash_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "amount": { "type": "string", "description": "Actual net Bank amount, in the selected account currency, independently entered. A positive amount is required except for an explicit, exactly balanced zero offset of two positive opposing native claims. A zero offset creates no Bank movement or matchable Bank source. With a foreign account currency, the entered settlement exchange rate values the gross allocations; it does not create a fictitious Bank movement. Currency minor-unit precision applies, with no silent rounding.", "maxLength": 40 }, "public_id": { "type": [ "string", "null" ], "minLength": 26, "maxLength": 26, "description": "Existing payment identity on correction; omit for a new payment. Reusing an unrelated payment identity is rejected." }, "transaction_amount": { "type": [ "string", "null" ], "maxLength": 40, "description": "Amount settled in instrument currency. In the original combined single-currency contract it covers net consideration including costs/withholding. With separately represented fee claims it covers only the transaction plus applicable withholding. Required when account and claim currencies differ; in the same currency a supplied amount must equal the amount established by actual cash and the explicit fee allocation. Fees-only settles zero transaction amount." }, "fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only for a Bank currency different from the administration base currency. Its actual cash rate applies on settlement date, separately from trade_fx." }, "day_order": { "type": [ "string", "null" ], "maxLength": 64, "description": "before: or after: from cash-day-order. For a subsequent pending row, before:row- or after:row-. First movement on an empty account/day requires no choice; unchanged retained payments preserve their placement. No number or timestamp input." }, "settles": { "type": "string", "enum": [ "both", "transaction", "fees" ], "description": "Which claim this actual Bank movement settles. Omitted means both for compatibility. Fees can be paid from another account/date than the transaction, even in the same currency." }, "fee_amount": { "type": [ "string", "null" ], "maxLength": 40, "description": "Fee-currency amount settled. Required for a combined payment with separate fee currency, or fees paid in another account currency. For fees-only in the same account currency, the actual account amount supplies it. May be zero when this combined payment settles no remaining fees." }, "fee_cash_amount": { "type": [ "string", "null" ], "maxLength": 40, "description": "Part of the actual Bank amount used for fees, in Bank currency. Required for a combined payment when Bank currency differs from fee currency. If fee currency equals Bank currency it equals fee_amount; for fees-only it equals amount. For a receipt net of paid fees, the gross transaction receipt equals the net receipt plus this fee part." }, "cash_direction": { "type": [ "string", "null" ], "enum": [ "pay", "receive", null ], "description": "Actual Bank direction. Required only for a combined payment settling both an incoming transaction and outgoing fees, where the actual net direction cannot be presumed. Else direction follows the selected claim; conflicting values are rejected." } }, "additionalProperties": false, "description": "Actual Bank settlement: own account, date, amount and optional recorded account-to-base FX. A payment may settle transaction, costs or both. Claims in distinct currencies have independent native amounts and explicit cash allocation when required. One payment creates at most one actual Bank movement; no purchase rate or invented currency allocation is used." }, "FreshSharesTradeInput": { "type": "object", "description": "Fresh shares source input. Shares and Bank cash may use distinct supported currencies. The source keeps native consideration, actual cash, native amount settled and separate recorded trade/payment rates. GL amounts and historic share cost use administration base currency. All Bank accounts are selectable; only the exact original payment may retain an inactive account during correction. Weighted average is shared administration-wide across brokers for the same instrument, with separate long/short pools and depot quantities. No costing-method or timestamp field. New-instrument facts are explicitly required. A nonzero withholding amount requires withholding_treatment. Direct fees use the fixed cost rules; fee_treatment is not accepted. Historical share-cost corrections recalculate only the source-connected instrument histories, including declared conversion targets; all affected open-period journals are stored atomically. A meaningful reference or payment-only source change retains the trade journal rows and revision when its date, fiscal year and monetary lines remain identical. Source history is kept in central financial audit; retry records hold source references, not another financial archive. Foreign-money dependencies are separately scoped to touched monetary accounts and jointly reviewed/stored; every participant is authorized and locked. Owned and short shares in the same instrument cannot overlap in the same broker account, including via historical corrections or received shares. Different broker accounts remain separate. Close the existing position explicitly before opening the other direction; no automatic trade netting or reclassification.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "buy", "sell", "short_sell", "short_cover" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A share public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "share" ], "maxLength": 255 }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false }, "FreshSharesPreview": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "input", "plan", "can_confirm", "confirmation_token" ], "properties": { "input": { "$ref": "#/components/schemas/FreshSharesSourceInput" }, "plan": { "$ref": "#/components/schemas/FreshSharesPlan", "properties": { "option_facts": { "$ref": "#/components/schemas/FreshOptionsContractFacts" } } }, "confirmation_token": { "type": "string", "description": "Sealed recipe for this proposal; it is bound to the current principal, administration, command key and operation." }, "can_confirm": { "type": "boolean", "const": true } } } } }, "FreshSharesConfirmation": { "type": "object", "additionalProperties": false, "required": [ "confirmation_token" ], "properties": { "confirmation_token": { "type": "string", "description": "Sealed proposal obtained with the same principal, administration, operation, source and Idempotency-Key. Changed source/account/period state requires a new proposal." } } }, "FreshSharesJournalLine": { "type": "object", "required": [ "account", "side", "storage_amount" ], "properties": { "account": { "type": "string" }, "ledger_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "storage_amount": { "type": "string", "description": "Exact four-decimal general-ledger amount." } } }, "FreshSharesPlan": { "type": "object", "description": "One source preview from the monthly valuation engine. Intrinsic source journals retain their identities; current results come from the persistent moving-average index or the same engine chronological strategy. Whole changed monthly reconciliation journals are shown before/after; unchanged later ordinary transaction journals remain untouched.", "required": [ "public_id", "currency", "lines", "settlements", "outstanding", "processed_transactions", "dependent_transactions", "dependencies", "cash_changes" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "input": { "$ref": "#/components/schemas/FreshSharesSourceInput" }, "position": { "type": [ "object", "null" ], "description": "State after this source: side/opening, exact quantity, remaining total historic cost, administration-wide pools and separate depot quantities. Long GAK has exact rational and explicitly rounded/approximate display values; shorts have null GAK. Money-only sources instead use {source_kind: cash}, without quantity, GAK or cost projections; positions is empty and processed_transactions is 0. Future sources use source_kind: future, long/short contract-count projections and actual realized_result. Daily sources have side and quantity_after null; GAK is null. Internal zero cost components are compatibility values, not a market valuation or asset. Participation sources expose historical cost, fiscal carrying and dated taxed/untaxed reserve balances separately, plus explicit exemption, relationship, non-deductible costs and liquidation-loss facts. No automatic VPB return." }, "positions": { "type": [ "object", "array" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } }, "before_lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } }, "settlements": { "type": "array", "items": { "type": "object", "description": "Each actual payment contains public account/source identities and its original cash evidence. Separate fees have allocations with key transaction/fees, currency, native and outgoing. No SQL ids or claim_releases map are exposed. A combined payment has one Bank movement, including its actual cash FX evidence." } }, "settlement_total": { "type": "string" }, "outstanding": { "type": "string" }, "outgoing": { "type": "boolean" }, "processed_transactions": { "type": "integer", "minimum": 0, "description": "Number of transitions evaluated by this proposal strategy; it is not a count of journal rewrites." }, "dependent_transactions": { "type": "integer", "minimum": 0 }, "dependencies": { "type": "array", "items": { "type": "object", "description": "Public source identity, actual date, before_calculation/calculation and journal_changed. Financial calculations include their GL lines. Earlier source versions remain internal audit records and are not loaded for detail, editing or preview." } }, "cash_changes": { "type": "array", "items": { "type": "object", "description": "before and after cash-entry facts: date, account label, amount, cash direction, GL lines. Null means added or removed." } }, "bank_reviews": { "type": "array", "items": { "type": "string", "minLength": 26, "maxLength": 26 }, "description": "Linked Bank entries requiring recheck after a cash-source change; no Bank entries are deleted or rebooked." }, "base_currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Currency of GL lines, historic cost, GAK and carrying amounts. currency is the instrument transaction currency." }, "fx_changes": { "type": "array", "items": { "type": "object", "description": "Only financially changed retained currency journals, with public journal identity, date, description, base currency, before_lines and lines. Jointly included in confirmation." } }, "outstanding_claims": { "type": "array", "description": "Separate native claim remainders, keyed transaction or fees; each has its own currency, direction and native amount. No SQL identities or cross-currency total. Present when fees are in a different currency or payments explicitly separate fees.", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "transaction", "fees" ] }, "currency": { "type": "string" }, "native": { "type": "string" }, "outgoing": { "type": "boolean" } }, "required": [ "key", "currency", "native", "outgoing" ], "additionalProperties": false } }, "deduction_year": { "type": [ "object", "null" ], "description": "Selected liquidation-loss year, with public identity, label, starts_on, ends_on and status. Never a SQL identity." }, "group_changes": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupChange" } }, "route": { "type": "string", "enum": [ "indexed_amount", "structural" ], "description": "Computational strategy within one accounting engine." }, "monthly_journals": { "type": "array", "items": { "type": "object", "required": [ "date", "lines", "before_lines", "journal_entry_public_id" ], "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } }, "before_lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } }, "journal_entry_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } } } }, "source_journals": { "type": "array", "items": { "type": "object", "required": [ "public_id", "date", "lines" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "date": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } } } } }, "removed_sources": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" } } } }, "FreshSharesResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "public_id", "journal_entry_public_id", "revision", "input", "calculation" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "journal_entry_public_id": { "type": [ "string", "null" ], "minLength": 26, "maxLength": 26, "description": "Null for a source-only opening, quantity event, cost continuation or no-change valuation. No synthetic journal identity." }, "revision": { "type": "integer", "minimum": 1 }, "removed": { "type": "boolean" }, "input": { "anyOf": [ { "$ref": "#/components/schemas/FreshSharesSourceInput" }, { "type": "null" } ] }, "calculation": { "type": [ "object", "null" ] }, "dependent_transactions": { "type": "integer", "minimum": 0 }, "bank_reviews": { "type": "array", "items": { "type": "string", "minLength": 26, "maxLength": 26 } }, "option_facts": { "$ref": "#/components/schemas/FreshOptionsContractFacts" } } } } }, "FreshSharesDetail": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Source and journal public identities, revision, current input and calculation, share/depot labels, outstanding amount, active payment identities and dated cash-journal identities. Detail returns only the current source state; it does not read or expose earlier audit versions or a history field. Earlier financial versions remain solely in the central audit under its existing retention policy. Removed sources return only public source/journal identities, revision, removed=true, removed_at, null input/calculation and empty settlements. No instrument, broker, currency or outstanding facts remain in that detail. Cash interest and account-cost sources return instrument=null and their explicitly entered currency; they have no security quantity, cost basis or year valuation.", "not": { "required": [ "history" ] }, "oneOf": [ { "type": "object", "required": [ "public_id", "revision", "removed", "input", "calculation" ], "properties": { "removed": { "type": "boolean", "const": false }, "input": { "type": "object" }, "calculation": { "type": "object" }, "outstanding_claims": { "type": "array", "description": "Separate native claim remainders, keyed transaction or fees; each has its own currency, direction and native amount. No SQL identities or cross-currency total. Present when fees are in a different currency or payments explicitly separate fees.", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "transaction", "fees" ] }, "currency": { "type": "string" }, "native": { "type": "string" }, "outgoing": { "type": "boolean" } }, "required": [ "key", "currency", "native", "outgoing" ], "additionalProperties": false } }, "instrument": { "type": [ "object", "null" ], "description": "Current investment facts for security sources; null for cash interest and account costs. Cash sources never create an investment instrument." } } }, { "$ref": "#/components/schemas/FreshSharesRemovedDetail" } ], "properties": { "option_facts": { "$ref": "#/components/schemas/FreshOptionsContractFacts" } } }, "group_adjustments": { "type": "array", "items": { "type": "object" } } } }, "FreshSharesOverview": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "positions", "transactions", "asOf" ], "properties": { "asOf": { "type": "string", "format": "date", "description": "Today in the administration timezone; later trades are excluded from positions." }, "positions": { "type": "array", "items": { "type": "object", "description": "Separate depot and long/short rows with exact quantity, remaining total historic cost and shared long GAK. Future rows have exact long/short contract counts and null cost, cost_exact, book_value and GAK; these monetary values are inapplicable. Book value includes active dated group corrections; ordinary_book_value and group_adjustment expose the ordinary carrying value and group component. Historic cost and GAK exclude the correction." }, "description": " Current descriptive name and external_identifier remain visible after instrument metadata correction; option contract labels supplement the current name." }, "transactions": { "type": "object", "description": "Laravel page of 25 active instrument trades and currency exchanges, newest transaction date first. Equal dates use source kind, descending instrument sort order, then public ID for stable display; this is not a claim about intraday cash chronology. Future entries remain visible with their date. Currency exchange rows have instrument_kind exchange, null quantity and exact sold/bought native amounts with currency codes and bank names; they do not create instrument positions. Security rows expose current external_identifier and instrument_currency_code; it is null for cash sources. No financial input or historical creation facts are rewritten." } } } }, "description": " Option positions and transaction rows expose their locale-formatted contract name and, when known, underlying_name separately. Underlying metadata is read in one administration-scoped batch without rebuilding positions." }, "FreshSharesRemovedDetail": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "journal_entry_public_id", "removed", "removed_at", "input", "calculation", "settlements" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "revision": { "type": "integer", "minimum": 1 }, "journal_entry_public_id": { "type": [ "string", "null" ], "minLength": 26, "maxLength": 26, "description": "Null for a source-only opening, quantity event, cost continuation or no-change valuation. No synthetic journal identity." }, "removed": { "type": "boolean", "const": true }, "removed_at": { "type": "string", "format": "date-time" }, "input": { "type": "null" }, "calculation": { "type": "null" }, "settlements": { "type": "array", "maxItems": 0 } } }, "FreshSharesFxInput": { "type": "object", "required": [ "conversion_mode" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": [ "string", "null" ], "maxLength": 40 }, "converted_base_amount": { "type": [ "string", "null" ], "maxLength": 40, "pattern": "^\\d+(?:[.,]\\d+)?$" } }, "oneOf": [ { "required": [ "rate" ], "properties": { "conversion_mode": { "const": "rate" } }, "not": { "required": [ "converted_base_amount" ] } }, { "required": [ "converted_base_amount" ], "properties": { "conversion_mode": { "const": "converted_amount" } }, "not": { "required": [ "rate" ] } } ], "description": "Explicit rate or converted actual net amount; no rate is inferred from the purchase or looked up externally. Localized comma or point decimals are accepted." }, "FreshSharesOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A share public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long", "opening_short" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Specification of an existing opening balance. No purchase, payment or journal is created. New-instrument identity/listing/currency facts follow the trade contract. Source confirmation, detail, correction and minimal deletion use the same endpoints and principal/tenant protections. A later disposal releases weighted-average historic cost and carrying value separately. Staged specification differences must be resolved before closing." }, "FreshSharesSourceInput": { "anyOf": [ { "$ref": "#/components/schemas/FreshSharesTradeInput" }, { "$ref": "#/components/schemas/FreshSharesOpeningInput" }, { "$ref": "#/components/schemas/FreshSharesIncomeInput" }, { "$ref": "#/components/schemas/FreshSharesEventInput" }, { "$ref": "#/components/schemas/FreshSharesConversionInput" }, { "$ref": "#/components/schemas/FreshSharesValuationInput" }, { "$ref": "#/components/schemas/FreshOptionsTradeInput" }, { "$ref": "#/components/schemas/FreshOptionsOpeningInput" }, { "$ref": "#/components/schemas/FreshOptionsEventInput" }, { "$ref": "#/components/schemas/FreshOptionsValuationInput" }, { "$ref": "#/components/schemas/FreshFundsTradeInput" }, { "$ref": "#/components/schemas/FreshFundsOpeningInput" }, { "$ref": "#/components/schemas/FreshFundsIncomeInput" }, { "$ref": "#/components/schemas/FreshFundsEventInput" }, { "$ref": "#/components/schemas/FreshFundsConversionInput" }, { "$ref": "#/components/schemas/FreshFundsValuationInput" }, { "$ref": "#/components/schemas/FreshBondsTradeInput" }, { "$ref": "#/components/schemas/FreshBondsOpeningInput" }, { "$ref": "#/components/schemas/FreshBondsIncomeInput" }, { "$ref": "#/components/schemas/FreshBondsEventInput" }, { "$ref": "#/components/schemas/FreshBondsConversionInput" }, { "$ref": "#/components/schemas/FreshBondsValuationInput" }, { "$ref": "#/components/schemas/FreshBondsRedemptionInput" }, { "$ref": "#/components/schemas/FreshWarrantsTradeInput" }, { "$ref": "#/components/schemas/FreshWarrantsOpeningInput" }, { "$ref": "#/components/schemas/FreshWarrantsEventInput" }, { "$ref": "#/components/schemas/FreshWarrantsValuationInput" }, { "$ref": "#/components/schemas/FreshWarrantsConversionInput" }, { "$ref": "#/components/schemas/FreshWarrantsDistributionInput" }, { "$ref": "#/components/schemas/BrokerCashInput" }, { "$ref": "#/components/schemas/BrokerFuturesCountInput" }, { "$ref": "#/components/schemas/BrokerFuturesDailyInput" }, { "$ref": "#/components/schemas/FreshParticipationsTradeInput" }, { "$ref": "#/components/schemas/FreshParticipationsOpeningInput" }, { "$ref": "#/components/schemas/FreshParticipationsIncomeInput" }, { "$ref": "#/components/schemas/FreshParticipationsEventInput" }, { "$ref": "#/components/schemas/FreshParticipationsTransitionInput" }, { "$ref": "#/components/schemas/FreshParticipationsValuationInput" }, { "$ref": "#/components/schemas/FreshParticipationsConversionInput" }, { "$ref": "#/components/schemas/FreshTurbosTradeInput" }, { "$ref": "#/components/schemas/FreshTurbosOpeningInput" }, { "$ref": "#/components/schemas/FreshTurbosEventInput" }, { "$ref": "#/components/schemas/FreshTurbosValuationInput" }, { "$ref": "#/components/schemas/FreshCryptoTradeInput" }, { "$ref": "#/components/schemas/FreshCryptoOpeningInput" }, { "$ref": "#/components/schemas/FreshCryptoValuationInput" }, { "$ref": "#/components/schemas/FreshCryptoConversionInput" }, { "$ref": "#/components/schemas/FreshCryptoReceiptInput" } ], "description": "Broker source input for shares, options, funds/ETF units, bonds, warrants/rights and money-only interest or account costs. Each module has its own form; financial confirmation, journals, Bank, FX and lifecycle share one contract. Futures have their own contract-count and daily-result forms, no cost-basis calculation. Turbo securities have their own trading, event, opening and year-end forms; CFDs are not supported by pretending they are share acquisitions. Crypto: buy, sell, explicit-value coin exchange, zero-cost airdrops and staking rewards, opening balance specification and cost-or-lower-market year value. No mandatory broker bank and no short positions." }, "FreshSharesIncomeInput": { "type": "object", "additionalProperties": false, "description": "Cash dividend gross principal in instrument currency. Stock distributions require positive quantity and explicitly declared gross distribution_value in administration base currency; principal is the actual cash component (zero when absent). Dividend and distribution handling costs are booked separately. No automatic participation exemption. Applicable zero canonical fields are accepted when reopening. Ordinary cash dividends have quantity zero; nonzero quantity is rejected. Participation income is entered with instrument_kind participation, not on a share.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "dividend_received", "stock_distribution_received" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A share public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "share" ], "maxLength": 255 }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "distribution_value": { "type": "string", "maxLength": 40, "description": "Required for stock distribution, nonnegative gross value in base currency. Unknown for cash dividend." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." }, "withholding_country_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Optional source withholding country from the existing application Countries list. Omitted/null remains unknown; never inferred from ISIN or a tax treatment." }, "dividend_payment_kind": { "type": [ "string", "null" ], "enum": [ "dividend", "substitute", "unknown", null ], "description": "Optional source classification. Descriptive only; actual gross/tax amounts and explicitly selected tax treatment are unchanged." } } }, "FreshSharesEventInput": { "type": "object", "additionalProperties": false, "description": "Existing instrument only. Transfer requires positive quantity and distinct destination broker Bank identity. Split requires a positive explicit numerator and denominator and acts on the entire instrument/side across brokers; quantity is zero. No fictitious consideration or fiscal exemption. Optional fees/tax use actual settlements, separate expense only. The unsuffixed action automatically uses the existing position direction in the selected broker account immediately before the event, according to its date and explicit within-day placement. Empty or conflicting positions are rejected. The confirmed source retains the resolved _long or _short action. Earlier explicit direction actions remain supported.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "transfer", "split", "transfer_long", "transfer_short", "split_long", "split_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A share public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "share" ], "maxLength": 255 }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "to_broker_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "split_numerator": { "type": "string", "maxLength": 40 }, "split_denominator": { "type": "string", "maxLength": 40 }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshSharesTargetInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "maxLength": 26, "description": "Existing target public identity, or new. A new identity is materialized once under the same atomic confirmation." }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_kind": { "type": "string", "enum": [ "share", "warrant" ], "description": "Explicit share or warrant/right kind for a new conversion target. Omission preserves the existing Shares API contract (share); a new right requires warrant. An existing target uses its recorded kind; any supplied kind must match. Option/right physical delivery still only accepts shares." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ] }, "instrument_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "cost_percentage": { "type": "string", "maxLength": 40, "description": "Cost-continuation only; declared allocation; all targets must total exactly 100." }, "base_value": { "type": "string", "maxLength": 40, "description": "Exchange only; explicitly declared nonnegative new cost/carrying in base currency." } }, "description": "Received or retained shares and allotted warrants/rights in a Shares conversion or exchange. Include retained original shares explicitly with the unchanged retained quantity and their declared basis percentage when allotting rights. New targets require name, listing and currency; no fiscal neutrality or allocation is inferred. Positive exact quantities and exactly closing basis allocations remain mandatory.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshSharesConversionInput": { "type": "object", "additionalProperties": false, "description": "Shares conversion or exchange with explicit share or warrant/right targets. Cost continuation requires a qualification reference and an exact declared 100 percent basis allocation, including retained shares when allotting rights. Exchange requires declared new base-currency target values and actual cash consideration. All connected histories and affected open journals are reviewed and saved atomically. No inferred fiscal neutrality or fictitious sale. The unsuffixed action automatically uses the existing position direction in the selected broker account immediately before the event, according to its date and explicit within-day placement. Empty or conflicting positions are rejected. The confirmed source retains the resolved _long or _short action. Earlier explicit direction actions remain supported.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "targets" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "conversion", "exchange", "conversion_long", "conversion_short", "exchange_long", "exchange_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A share public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "share" ], "maxLength": 255 }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FreshSharesTargetInput" } }, "qualification_reference": { "type": "string", "maxLength": 255 }, "exchange_cash_direction": { "type": "string", "enum": [ "receive", "pay" ] }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshSharesValuationInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "instrument_public_id", "action", "fiscal_year_public_id", "market_price" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A share public identity, or new.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "valuation_long", "valuation_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only when instrument and administration currencies differ. Converts native net consideration on trade date. Components round cumulatively to the exact converted net. Positive native amounts that convert to zero remain represented." }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required for nonzero net cash. For exactly zero net consideration no settlement fields apply: status is none and inactive settlement fields are ignored, in both website and API." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "market_price": { "type": "string", "maxLength": 40, "description": "Nonnegative price per registered share, not a rounded transaction money amount. No quotation date, source or invented factor." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Date is derived from actual fiscal-year end including broken years. Supplied trade_date must match. Ordinary long policy is historic cost or lower market; short liabilities are original consideration or higher settlement value. Price conversion is required only for a nonzero foreign market value, using an entered rate or actual converted total. No per-source method/policy. Participation sources use their own explicit fiscal-value/transition contract; linked fiscal valuation is never treated as an ordinary long automatically. All canonical zero fields may be returned and submitted unchanged during correction. A no-change value has no synthetic journal." }, "FreshSharesReconciliation": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "as_of", "currency_code", "positions", "accounts", "cash", "blockers", "reconciled", "external_statement_checked", "complete" ], "properties": { "as_of": { "type": "string", "format": "date" }, "currency_code": { "type": "string" }, "positions": { "type": "array", "items": { "type": "object", "description": "Current historical cost and book value from the authenticated valuation index or the single connected-instrument strategy. Book value includes the actual dated active group overlay; ordinary_book_value and group_adjustment distinguish its components. A historical source correction updates this projection without rewriting unchanged ordinary sale journals." } }, "accounts": { "type": "array", "items": { "type": "object", "description": "Signed base expected/actual/difference and optional native balances, with public ledger account metadata. Separate possession/liability accounts." } }, "cash": { "type": "array", "items": { "type": "object", "description": "Actual source cash movements and shared Bank/GL balances including other cash movements; no duplicate balance store." } }, "blockers": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "reconciled": { "type": "boolean" }, "external_statement_checked": { "type": "boolean", "const": false }, "group_valuations": { "type": "array", "items": { "type": "object" } }, "complete": { "type": "boolean", "description": "False when the control could not be completed. Empty positions on an incomplete control do not establish that no positions exist." }, "problem": { "type": [ "object", "null" ], "description": "Safe tenant-scoped context for an incomplete control; never raw exceptions or database identifiers.", "properties": { "phase": { "type": "string" }, "source_public_id": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string" }, "journal_public_id": { "type": "string" }, "journal_number": { "type": "integer" } } }, "broker_reconciliation": { "oneOf": [ { "$ref": "#/components/schemas/BrokerCalculatedReportReconciliation" }, { "type": "null" } ] } }, "description": "Sources, payment journals and position projections are proved against the actual ledger at the date. Later facts are excluded. Necessary current year-end values and relevant FX revaluations block fiscal close, checked again under lock at actual close. This does not verify a broker statement. Daily-settled futures show counts without a stock year valuation requirement. Daily monetary source facts are independently re-proved against journals. All entered daily results and pending cash, including relevant FX revaluations, remain in the dated ledger check; no external statement or unentered settlement dates are verified." } } }, "FreshOptionsTradeInput": { "type": "object", "description": "Options use the same Broker source, confirmation, Bank, currency, audit, correction and removal contract. No FIFO or guessed contract multiplier.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "buy", "sell", "short_sell", "short_cover" ], "maxLength": 255, "description": "buy opens/increases a purchased right; sell closes/reduces a purchased right; short_sell writes an obligation; short_cover closes/reduces a written obligation." }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Existing option public identity in this administration, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Generated from expiry, Call/Put, exact strike and strike currency. A supplied free name is replaced by that generated name on new options. Stored canonical name uses Dutch formatting; displays and detail/overview names follow the request locale. Existing legacy options keep their recorded name." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The one option contract currency for both strike and premium. Required when entering an underlying name or index; derived from a selected existing share otherwise. If supplied with a share, it must match that share." }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual total option premium in instrument currency, excluding fees and withholding. No multiplier is inferred. Maximum currency minor-unit decimals; excess precision is rejected.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "option" ], "description": "Required for a new option. Existing option references may omit the tag; the stored tenant-scoped instrument proves its kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "option_type": { "type": "string", "enum": [ "call", "put" ], "description": "Required only when creating a new option. No default or inference from name/identifier. On an existing option, omitted means use its recorded facts; a submitted value must match." }, "underlying_instrument_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "enum": [ null, "new" ] } ], "description": "Existing share identity in this administration, or null/new with underlying_name to enter another share or index. Ownership is not required; the new marker creates only descriptive contract facts, never a share or position. Supplied existing-contract facts must match." }, "underlying_name": { "type": [ "string", "null" ], "maxLength": 255, "minLength": 1, "description": "Name of a share or index not selected by underlying_instrument_public_id. Creating an option creates no underlying share or position. New options require exactly one existing share identity or a name. On existing options, submitted facts must match recorded facts." }, "expires_on": { "type": "string", "format": "date", "description": "Explicit contract expiry, required for new options. Descriptive identity only; no trade cutoff or automatic expiry posting is inferred." }, "strike_price": { "type": "string", "maxLength": 40, "pattern": "^\\d+(?:[.,]\\d+)?$", "description": "Exact non-negative strike per underlying unit, required for new options. No rounding, contract factor, delivery quantity or total payment is inferred." }, "strike_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Optional compatibility input for a new option. If supplied, it must equal the contract currency. The stored contract identity records this currency even when omitted from the request." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_listing", "option_type", "expires_on", "strike_price" ], "oneOf": [ { "required": [ "underlying_instrument_public_id" ], "properties": { "underlying_instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "underlying_name": { "type": "null" } } }, { "required": [ "underlying_name", "currency_code" ], "properties": { "underlying_name": { "type": "string", "minLength": 1 }, "underlying_instrument_public_id": { "enum": [ null, "new" ] } } } ] } } ] }, "FreshOptionsOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "Existing option public identity in this administration, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Generated from expiry, Call/Put, exact strike and strike currency. A supplied free name is replaced by that generated name on new options. Stored canonical name uses Dutch formatting; displays and detail/overview names follow the request locale. Existing legacy options keep their recorded name." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The one option contract currency for both strike and premium. Required when entering an underlying name or index; derived from a selected existing share otherwise. If supplied with a share, it must match that share." }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long", "opening_short" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "instrument_kind": { "type": "string", "enum": [ "option" ], "description": "Required for a new option. Existing option references may omit the tag; the stored tenant-scoped instrument proves its kind." }, "option_type": { "type": "string", "enum": [ "call", "put" ], "description": "Required only when creating a new option. No default or inference from name/identifier. On an existing option, omitted means use its recorded facts; a submitted value must match." }, "underlying_instrument_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "enum": [ null, "new" ] } ], "description": "Existing share identity in this administration, or null/new with underlying_name to enter another share or index. Ownership is not required; the new marker creates only descriptive contract facts, never a share or position. Supplied existing-contract facts must match." }, "underlying_name": { "type": [ "string", "null" ], "maxLength": 255, "minLength": 1, "description": "Name of a share or index not selected by underlying_instrument_public_id. Creating an option creates no underlying share or position. New options require exactly one existing share identity or a name. On existing options, submitted facts must match recorded facts." }, "expires_on": { "type": "string", "format": "date", "description": "Explicit contract expiry, required for new options. Descriptive identity only; no trade cutoff or automatic expiry posting is inferred." }, "strike_price": { "type": "string", "maxLength": 40, "pattern": "^\\d+(?:[.,]\\d+)?$", "description": "Exact non-negative strike per underlying unit, required for new options. No rounding, contract factor, delivery quantity or total payment is inferred." }, "strike_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Optional compatibility input for a new option. If supplied, it must equal the contract currency. The stored contract identity records this currency even when omitted from the request." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Options use the same Broker source, confirmation, Bank, currency, audit, correction and removal contract. No FIFO or guessed contract multiplier.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_listing", "option_type", "expires_on", "strike_price" ], "oneOf": [ { "required": [ "underlying_instrument_public_id" ], "properties": { "underlying_instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "underlying_name": { "type": "null" } } }, { "required": [ "underlying_name", "currency_code" ], "properties": { "underlying_name": { "type": "string", "minLength": 1 }, "underlying_instrument_public_id": { "enum": [ null, "new" ] } } } ] } } ] }, "FreshOptionsEventInput": { "type": "object", "additionalProperties": false, "description": "Options use the same Broker source, confirmation, Bank, currency, audit, correction and removal contract. No FIFO or guessed contract multiplier. For ordinary taxable physical delivery opening shares, only the added long or short basis has a zero floor; any excess is recognized in the existing joint realized securities result. Original option premium, earlier book valuations and the historical basis of existing shares remain separate and traceable.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "exercise_call", "exercise_put", "assign_call", "assign_put", "expire_long", "expire_short", "cash_settle_long", "cash_settle_short", "transfer_long", "transfer_short", "split_long", "split_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Existing option public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Generated from expiry, Call/Put, exact strike and strike currency. A supplied free name is replaced by that generated name on new options. Stored canonical name uses Dutch formatting; displays and detail/overview names follow the request locale. Existing legacy options keep their recorded name." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Total strike consideration for physical delivery, or actual gross cash settlement in option currency. Zero for expiry/transfer/split; no inferred contract factor.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "option" ], "description": "Required for a new option. Existing option references may omit the tag; the stored tenant-scoped instrument proves its kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "to_broker_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "split_numerator": { "type": "string", "maxLength": 40 }, "split_denominator": { "type": "string", "maxLength": 40 }, "delivery_action": { "type": "string", "enum": [ "buy", "sell", "short_sell", "short_cover" ], "description": "Required only for physical delivery: exercise_call/assign_put require buy or short_cover; exercise_put/assign_call require sell or short_sell. No automatic choice." }, "targets": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/FreshOptionsDeliveryTargetInput" } }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "option_type": { "type": "string", "enum": [ "call", "put" ], "description": "Required only when creating a new option. No default or inference from name/identifier. On an existing option, omitted means use its recorded facts; a submitted value must match." }, "underlying_instrument_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "enum": [ null, "new" ] } ], "description": "Existing share identity in this administration, or null/new with underlying_name to enter another share or index. Ownership is not required; the new marker creates only descriptive contract facts, never a share or position. Supplied existing-contract facts must match." }, "underlying_name": { "type": [ "string", "null" ], "maxLength": 255, "minLength": 1, "description": "Name of a share or index not selected by underlying_instrument_public_id. Creating an option creates no underlying share or position. New options require exactly one existing share identity or a name. On existing options, submitted facts must match recorded facts." }, "expires_on": { "type": "string", "format": "date", "description": "Explicit contract expiry, required for new options. Descriptive identity only; no trade cutoff or automatic expiry posting is inferred." }, "strike_price": { "type": "string", "maxLength": 40, "pattern": "^\\d+(?:[.,]\\d+)?$", "description": "Exact non-negative strike per underlying unit, required for new options. No rounding, contract factor, delivery quantity or total payment is inferred." }, "strike_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Recorded strike currency. For an existing option, an optionally supplied value must match the contract. For new options, this currency is derived from the selected share or the single chosen option currency." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "allOf": [ { "if": { "properties": { "action": { "enum": [ "exercise_call", "exercise_put", "assign_call", "assign_put" ] } }, "required": [ "action" ] }, "then": { "required": [ "quantity", "principal", "delivery_action", "targets" ] } }, { "if": { "properties": { "action": { "enum": [ "exercise_call", "assign_put" ] } }, "required": [ "action" ] }, "then": { "properties": { "delivery_action": { "enum": [ "buy", "short_cover" ] } } } }, { "if": { "properties": { "action": { "enum": [ "exercise_put", "assign_call" ] } }, "required": [ "action" ] }, "then": { "properties": { "delivery_action": { "enum": [ "sell", "short_sell" ] } } } }, { "if": { "properties": { "action": { "enum": [ "expire_long", "expire_short", "cash_settle_long", "cash_settle_short", "transfer_long", "transfer_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "quantity" ] } }, { "if": { "properties": { "action": { "enum": [ "cash_settle_long", "cash_settle_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "principal" ] } }, { "if": { "properties": { "action": { "enum": [ "transfer_long", "transfer_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "to_broker_public_id" ] } }, { "if": { "properties": { "action": { "enum": [ "split_long", "split_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "split_numerator", "split_denominator" ] } } ] }, "FreshOptionsValuationInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "instrument_public_id", "action", "fiscal_year_public_id", "market_price", "quote_basis" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "Existing option public identity in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "valuation_long", "valuation_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only when option and administration currencies differ. Converts the actual year-end market value; no purchase-date rate is silently reused." }, "quantity": { "type": "string", "description": "Derived zero compatibility value in normalized source input. Valuation applies to the actual open quantity proved at the fiscal-year end; users do not supply a quantity.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required for nonzero net cash. For exactly zero net consideration no settlement fields apply: status is none and inactive settlement fields are ignored, in both website and API." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "market_price": { "type": "string", "maxLength": 40, "description": "Nonnegative entered quote per complete contract or per underlying unit as explicitly selected in quote_basis. No source, quotation date or factor is guessed." }, "instrument_kind": { "type": "string", "enum": [ "option" ], "description": "Required for a new option. Existing option references may omit the tag; the stored tenant-scoped instrument proves its kind." }, "quote_basis": { "type": "string", "enum": [ "per_contract", "per_underlying_unit" ] }, "contract_factor": { "type": "string", "maxLength": 40, "description": "Explicit positive decimal factor, required only for per_underlying_unit; prohibited for per_contract. No default." }, "option_type": { "type": "string", "enum": [ "call", "put" ], "description": "Required only when creating a new option. No default or inference from name/identifier. On an existing option, omitted means use its recorded facts; a submitted value must match." }, "underlying_instrument_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "enum": [ null, "new" ] } ], "description": "Existing share identity in this administration, or null/new with underlying_name to enter another share or index. Ownership is not required; the new marker creates only descriptive contract facts, never a share or position. Supplied existing-contract facts must match." }, "underlying_name": { "type": [ "string", "null" ], "maxLength": 255, "minLength": 1, "description": "Name of a share or index not selected by underlying_instrument_public_id. Creating an option creates no underlying share or position. New options require exactly one existing share identity or a name. On existing options, submitted facts must match recorded facts." }, "expires_on": { "type": "string", "format": "date", "description": "Explicit contract expiry, required for new options. Descriptive identity only; no trade cutoff or automatic expiry posting is inferred." }, "strike_price": { "type": "string", "maxLength": 40, "pattern": "^\\d+(?:[.,]\\d+)?$", "description": "Exact non-negative strike per underlying unit, required for new options. No rounding, contract factor, delivery quantity or total payment is inferred." }, "strike_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Recorded strike currency. For an existing option, an optionally supplied value must match the contract. For new options, this currency is derived from the selected share or the single chosen option currency." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Purchased option rights: historical cost or lower market value. Written option liabilities: received premium basis or higher settlement value. Ordinary independent positions only; no implicit exemption or hedge classification. Date is the actual selected fiscal-year end.", "allOf": [ { "if": { "properties": { "quote_basis": { "const": "per_underlying_unit" } }, "required": [ "quote_basis" ] }, "then": { "required": [ "contract_factor" ] } }, { "if": { "properties": { "quote_basis": { "const": "per_contract" } }, "required": [ "quote_basis" ] }, "then": { "not": { "required": [ "contract_factor" ] } } } ] }, "FreshOptionsDeliveryTargetInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "maxLength": 26, "description": "Existing target public identity, or new. A new identity is materialized once under the same atomic confirmation." }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_kind": { "type": "string", "enum": [ "share" ], "description": "Optional explicit share kind. Actual delivery only targets shares. A new target is stored as a share; there is no inferred quantity or contract factor." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ] }, "instrument_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 } }, "description": "Actual delivered share quantity. Only shares are supported; no inferred quantity, cost allocation or contract factor. New shares require name, listing and currency.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshOptionsContractFacts": { "type": "object", "description": "Recorded option identity, with optional existing underlying share. Missing historical facts remain unknown. No share ownership or fiscal hedge is implied. New contract names use these exact facts.", "properties": { "option_type": { "type": [ "string", "null" ], "enum": [ "call", "put", null ] }, "underlying": { "type": [ "object", "null" ], "properties": { "public_id": { "type": "string" }, "name": { "type": "string" }, "revision": { "type": "integer" } } }, "underlying_name": { "type": [ "string", "null" ], "maxLength": 255, "minLength": 1, "description": "Name of a share or index not selected by underlying_instrument_public_id. Creating an option creates no underlying share or position. New options require exactly one existing share identity or a name. On existing options, submitted facts must match recorded facts." }, "expires_on": { "type": "string", "format": "date", "description": "Explicit contract expiry, required for new options. Descriptive identity only; no trade cutoff or automatic expiry posting is inferred." }, "strike_price": { "type": "string", "maxLength": 40, "pattern": "^\\d+(?:[.,]\\d+)?$", "description": "Exact non-negative strike per underlying unit, required for new options. No rounding, contract factor, delivery quantity or total payment is inferred." }, "strike_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Recorded strike currency. For an existing option, an optionally supplied value must match the contract. For new options, this currency is derived from the selected share or the single chosen option currency." } } }, "FreshFundsTradeInput": { "type": "object", "description": "ETF/fund units using the shared Broker financial contract. Weighted average cost including acquisition fees; no underlying-holdings look-through. Fund/ETF trade source input. Fund units and Bank cash may use distinct supported currencies. The source keeps native consideration, actual cash, native amount settled and separate recorded trade/payment rates. GL amounts and historic unit cost use administration base currency. All Bank accounts are selectable; only the exact original payment may retain an inactive account during correction. Weighted average is shared administration-wide across brokers for the same instrument, with separate long/short pools and depot quantities. No costing-method or timestamp field. New-instrument facts are explicitly required. A nonzero withholding amount requires withholding_treatment. Direct fees use the fixed cost rules; fee_treatment is not accepted. Historical share-cost corrections recalculate only the source-connected instrument histories, including declared conversion targets; all affected open-period journals are stored atomically. A meaningful reference or payment-only source change retains the trade journal rows and revision when its date, fiscal year and monetary lines remain identical. Source history is kept in central financial audit; retry records hold source references, not another financial archive. Foreign-money dependencies are separately scoped to touched monetary accounts and jointly reviewed/stored; every participant is authorized and locked.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "buy", "sell", "short_sell", "short_cover" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A fund public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "fund" ], "description": "Required for a new fund. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshFundsOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A fund public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long", "opening_short" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "instrument_kind": { "type": "string", "enum": [ "fund" ], "description": "Required for a new fund. Existing instrument references retain their stored kind." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "ETF/fund units using the shared Broker financial contract. Weighted average cost including acquisition fees; no underlying-holdings look-through. Specification of an existing opening balance. No purchase, payment or journal is created. New-instrument identity/listing/currency facts follow the trade contract. Source confirmation, detail, correction and minimal deletion use the same endpoints and principal/tenant protections. A later disposal releases weighted-average historic cost and carrying value separately. Staged specification differences must be resolved before closing.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshFundsIncomeInput": { "type": "object", "additionalProperties": false, "description": "ETF/fund units using the shared Broker financial contract. Weighted average cost including acquisition fees; no underlying-holdings look-through. Cash dividend gross principal in instrument currency. Stock distributions require positive quantity and explicitly declared gross distribution_value in administration base currency; principal is the actual cash component (zero when absent). Dividend and distribution handling costs are booked separately. No automatic participation exemption. Applicable zero canonical fields are accepted when reopening. Ordinary cash dividends have quantity zero; nonzero quantity is rejected.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "dividend_received", "stock_distribution_received" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A fund public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "fund" ], "description": "Required for a new fund. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "distribution_value": { "type": "string", "maxLength": 40, "description": "Required for stock distribution, nonnegative gross value in base currency. Unknown for cash dividend." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." }, "withholding_country_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Optional source withholding country from the existing application Countries list. Omitted/null remains unknown; never inferred from ISIN or a tax treatment." }, "dividend_payment_kind": { "type": [ "string", "null" ], "enum": [ "dividend", "substitute", "unknown", null ], "description": "Optional source classification. Descriptive only; actual gross/tax amounts and explicitly selected tax treatment are unchanged." } }, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshFundsEventInput": { "type": "object", "additionalProperties": false, "description": "ETF/fund units using the shared Broker financial contract. Weighted average cost including acquisition fees; no underlying-holdings look-through. Existing instrument only. Transfer requires positive quantity and distinct destination broker Bank identity. Split requires a positive explicit numerator and denominator and acts on the entire instrument/side across brokers; quantity is zero. No fictitious consideration or fiscal exemption. Optional fees/tax use actual settlements, separate expense only. Neutral actions derive the position direction from the selected account immediately before the event in its actual date/order. The confirmed source stores the resolved directional action. No simultaneous long and short position in the same security/account; different accounts stay separate.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "transfer", "split", "transfer_long", "transfer_short", "split_long", "split_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A fund public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "fund" ], "description": "Required for a new fund. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "to_broker_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "split_numerator": { "type": "string", "maxLength": 40 }, "split_denominator": { "type": "string", "maxLength": 40 }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshFundsConversionInput": { "type": "object", "additionalProperties": false, "description": "ETF/fund units using the shared Broker financial contract. Weighted average cost including acquisition fees; no underlying-holdings look-through. Cost continuation requires qualification_reference and exact declared 100 percent basis allocation; historical cost and book value remain separately traceable. Exchange requires principal (actual cash component, possibly zero), exchange_cash_direction and explicit base_value per target. All linked target histories and dependent open-period journals are checked and stored atomically. No automatic neutrality or fictitious sale. Neutral actions derive the position direction from the selected account immediately before the event in its actual date/order. The confirmed source stores the resolved directional action. No simultaneous long and short position in the same security/account; different accounts stay separate.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "targets" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "conversion", "exchange", "conversion_long", "conversion_short", "exchange_long", "exchange_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A fund public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "fund" ], "description": "Required for a new fund. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FreshFundsTargetInput" } }, "qualification_reference": { "type": "string", "maxLength": 255 }, "exchange_cash_direction": { "type": "string", "enum": [ "receive", "pay" ] }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshFundsValuationInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "instrument_public_id", "action", "fiscal_year_public_id", "market_price" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A fund public identity in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "valuation_long", "valuation_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only when instrument and administration currencies differ. Converts native net consideration on trade date. Components round cumulatively to the exact converted net. Positive native amounts that convert to zero remain represented." }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required for nonzero net cash. For exactly zero net consideration no settlement fields apply: status is none and inactive settlement fields are ignored, in both website and API." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "market_price": { "type": "string", "maxLength": 40, "description": "Nonnegative price per registered fund unit, not a rounded transaction money amount. No quotation date, source or invented factor." }, "instrument_kind": { "type": "string", "enum": [ "fund" ], "description": "Required for a new fund. Existing instrument references retain their stored kind." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "ETF/fund units using the shared Broker financial contract. Weighted average cost including acquisition fees; no underlying-holdings look-through. Date is derived from actual fiscal-year end including broken years. Supplied trade_date must match. Ordinary long policy is historic cost or lower market; short liabilities are original consideration or higher settlement value. Price conversion is required only for a nonzero foreign market value, using an entered rate or actual converted total. No per-source method/policy. Participation/linked fiscal valuation is deferred, never treated as an ordinary long automatically. All canonical zero fields may be returned and submitted unchanged during correction. A no-change value has no synthetic journal." }, "FreshFundsTargetInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "maxLength": 26, "description": "Existing target public identity, or new. A new identity is materialized once under the same atomic confirmation." }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_kind": { "type": "string", "enum": [ "fund" ], "description": "Optional explicit fund kind. Omission on a new target records fund, as fixed by the source module." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ] }, "instrument_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "cost_percentage": { "type": "string", "maxLength": 40, "description": "Cost-continuation only; declared allocation; all targets must total exactly 100." }, "base_value": { "type": "string", "maxLength": 40, "description": "Exchange only; explicitly declared nonnegative new cost/carrying in base currency." } }, "description": "Existing or new fund/ETF units only. A new target requires its name, listing, currency; its type follows the fund source module; existing targets retain their stored fund identity. Positive exact unit quantities are required. Explicit basis allocations or exchange values are supplied by the source event.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshBondsTradeInput": { "type": "object", "description": "Bond purchase, sale, short opening or buyback using the shared Broker command. Clean consideration and capitalized trading fees determine weighted cost; accrued interest is a separate monetary asset or liability. Native consideration, fees in their own currency, actual Bank payments and separate trade/payment conversions remain explicit. Selected earlier interest items are released only by an explicit source allocation. Historical corrections replay only connected instrument histories and touched monetary accounts, review all affected open-period journals and save atomically. No FIFO, time, fee-treatment choice, nominal-value assumption or coupon schedule.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "buy", "sell", "short_sell", "short_cover" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A bond public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "bond" ], "description": "Required for a new bond. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "accrued_interest": { "type": [ "string", "null" ], "maxLength": 40, "description": "Optional native accrued interest paid/received alongside the clean bond consideration; blank/null is zero. Never capitalized into security cost." }, "interest_allocations": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/FreshBondsInterestAllocation" }, "description": "Only for sale/cover: explicit earlier same-bond same-side interest source amounts, not an automatic allocation." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshBondsOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A bond public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long", "opening_short" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "instrument_kind": { "type": "string", "enum": [ "bond" ], "description": "Required for a new bond. Existing instrument references retain their stored kind." }, "opening_interest": { "type": [ "string", "null" ], "maxLength": 40, "description": "Optional native accrued interest already separately present in the existing opening ledger on its date. Blank means zero, never the whole later coupon." }, "opening_interest_carrying": { "type": [ "string", "null" ], "maxLength": 40, "description": "Existing accrued-interest carrying value in administration currency. Required for positive foreign-currency interest; equal to native interest in base currency. Never posts an additional opening journal." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Specification of bond quantity, historical cost and carrying value against the existing opening balance. No purchase, payment or new journal. New instrument identity, listing and currency remain explicit. The same confirmation, detail, correction and minimal tombstone routes apply; specification differences block year closing. Separate existing opening interest is optional; later explicitly selected releases retain the original native amount and carrying value.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshBondsEventInput": { "type": "object", "additionalProperties": false, "description": "Transfer or split of an existing bond position. Transfer requires explicit positive quantity and a distinct destination Bank identity. Split uses an explicit positive numerator and denominator for the entire instrument and side across brokers. The event preserves historical cost and carrying value without fictitious consideration. Optional actual fees and withholding use the existing settlement and foreign-currency contract. Neutral actions derive the position direction from the selected account immediately before the event in its actual date/order. The confirmed source stores the resolved directional action. No simultaneous long and short position in the same security/account; different accounts stay separate.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "transfer", "split", "transfer_long", "transfer_short", "split_long", "split_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A bond public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "bond" ], "description": "Required for a new bond. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "to_broker_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "split_numerator": { "type": "string", "maxLength": 40 }, "split_denominator": { "type": "string", "maxLength": 40 }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshBondsConversionInput": { "type": "object", "additionalProperties": false, "description": "Conversion or exchange of bonds into explicitly selected bonds or shares. Cost continuation requires a qualification reference and an exact declared 100 percent basis allocation. Exchange requires actual cash consideration/direction and declared base-currency target values. Interest received for long positions or paid for short positions remains separate from security cost and may offset the actual cash consideration. Explicit earlier-interest allocations release only the selected sources. All connected histories, interest, money and affected open journals are reviewed and saved atomically. No automatic fiscal neutrality. Neutral actions derive the position direction from the selected account immediately before the event in its actual date/order. The confirmed source stores the resolved directional action. No simultaneous long and short position in the same security/account; different accounts stay separate.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "targets" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "conversion", "exchange", "conversion_long", "conversion_short", "exchange_long", "exchange_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A bond public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual cash consideration of the exchange in bond currency, excluding fees, withholding and separate interest. Continuation permits only zero. Interest retains its own direction (received on long bonds; paid on short obligations); settlements declare the actual net cash amount.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "bond" ], "description": "Required for a new bond. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount. Gross cash consideration and separate interest in foreign currency still require conversion when they offset exactly to zero. In that case enter the actual rate; a zero net base equivalent cannot establish a rate." }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FreshBondsTargetInput" } }, "qualification_reference": { "type": "string", "maxLength": 255 }, "exchange_cash_direction": { "type": "string", "enum": [ "receive", "pay" ] }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "accrued_interest": { "type": [ "string", "null" ], "maxLength": 40, "description": "Optional separate interest received for a long conversion/exchange or paid for a short one. Blank/null/omitted means zero. Never part of share cost. Monetary precision follows bond currency." }, "interest_allocations": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/FreshBondsInterestAllocation" }, "description": "Explicit earlier same-bond same-side interest source amounts released by this event. No automatic allocation; unused interest remains separately traceable even after the bond position is closed." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshBondsValuationInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "instrument_public_id", "action", "fiscal_year_public_id", "market_price", "quote_basis" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A bond public identity in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "valuation_long", "valuation_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only when instrument and administration currencies differ. Converts native net consideration on trade date. Components round cumulatively to the exact converted net. Positive native amounts that convert to zero remain represented." }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required for nonzero net cash. For exactly zero net consideration no settlement fields apply: status is none and inactive settlement fields are ignored, in both website and API." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "market_price": { "type": "string", "maxLength": 40, "description": "Nonnegative price per registered bond, not a rounded transaction money amount. No quotation date, source or invented factor." }, "instrument_kind": { "type": "string", "enum": [ "bond" ], "description": "Required for a new bond. Existing instrument references retain their stored kind." }, "quote_basis": { "type": "string", "enum": [ "per_piece", "percent_nominal" ] }, "nominal_per_piece": { "type": "string", "maxLength": 40, "description": "Positive explicit face value per registered bond, required only for percent_nominal. No default factor." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Ordinary bond year value at the actual fiscal-year end, including broken fiscal years. The explicit quotation is per registered bond or a percentage of an explicitly entered face value per bond; no default face value. Long positions use cost or lower market value; short liabilities use original net proceeds or higher settlement value. Accrued interest stays separate. A nonzero foreign market total requires an entered rate or converted total. Historical cost remains traceable, dependent open-period corrections use the shared route, and no-change valuation creates no fake journal." }, "FreshBondsInterestAllocation": { "type": "object", "additionalProperties": false, "required": [ "source_public_id", "amount" ], "properties": { "source_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "amount": { "type": "string", "maxLength": 40, "description": "Positive exact native interest amount, limited to the selected source outstanding at the actual transaction order." } }, "description": "An explicit allocation to a source-public identity from an earlier bond trade in the same administration, instrument and long/short side. The amount is in the bond currency and cannot exceed either its remaining interest or the interest being received/paid. No automatic allocation." }, "FreshBondsIncomeInput": { "type": "object", "description": "Coupon received or paid. Principal is the full coupon before actual fees and withholding. Quantity is zero and no accrued_interest field is accepted. Explicit interest_allocations release earlier purchased-interest assets or short coupon liabilities; only the remaining coupon is new interest income or expense. Foreign releases use historical or dated-revalued carrying amounts with a separate realized FX result. Uses the shared Bank, confirmation, correction and removal contract.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "coupon", "coupon_paid" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A bond public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "const": "0" }, "principal": { "type": "string", "description": "Full gross native coupon before fees/withholding. Explicit earlier interest allocations reduce new interest income/expense, not gross cash.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "bond" ], "description": "Required for a new bond. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "interest_allocations": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/FreshBondsInterestAllocation" }, "description": "Only for sale/cover: explicit earlier same-bond same-side interest source amounts, not an automatic allocation." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshBondsRedemptionInput": { "type": "object", "description": "Bond redemption, with explicit positive quantity, clean repayment consideration and optional separately declared interest. Long redemption removes an asset; short redemption closes a liability. Direct fees follow the existing fixed net-result rule. Explicit allocations may release earlier interest; no nominal repayment amount, coupon schedule or fiscal result is inferred. Actual Bank cash, native amount settled, fee currency, conversions and open-period dependent corrections use the shared contract. Neutral actions derive the position direction from the selected account immediately before the event in its actual date/order. The confirmed source stores the resolved directional action. No simultaneous long and short position in the same security/account; different accounts stay separate.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "redeem", "redeem_long", "redeem_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A bond public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "bond" ], "description": "Required for a new bond. Existing instrument references retain their stored kind." }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "accrued_interest": { "type": [ "string", "null" ], "maxLength": 40, "description": "Optional native accrued interest paid/received alongside the clean bond consideration; blank/null is zero. Never capitalized into security cost." }, "interest_allocations": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/FreshBondsInterestAllocation" }, "description": "Only for sale/cover: explicit earlier same-bond same-side interest source amounts, not an automatic allocation." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshWarrantsTradeInput": { "type": "object", "description": "Warrant/right trade input through the shared Broker financial contract. Exact quantities, weighted average cost and actual cash movements. No inferred contract factor, tax exemption or cost-neutral qualification.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "buy", "sell", "short_sell", "short_cover" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A fund public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Name recorded by the user for this warrant or right." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual total gross consideration in warrant/right currency, excluding fees and withholding.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "warrant" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshWarrantsOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A fund public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Name recorded by the user for this warrant or right." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long", "opening_short" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "instrument_kind": { "type": "string", "const": "warrant" }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Warrant/right opening input through the shared Broker financial contract. Exact quantities, weighted average cost and actual cash movements. No inferred contract factor, tax exemption or cost-neutral qualification.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshWarrantsEventInput": { "type": "object", "additionalProperties": false, "description": "Warrant/right event input through the shared Broker financial contract. Exact quantities, weighted average cost and actual cash movements. No inferred contract factor, tax exemption or cost-neutral qualification.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "exercise_call", "exercise_put", "assign_call", "assign_put", "expire_long", "expire_short", "cash_settle_long", "cash_settle_short", "transfer_long", "transfer_short", "split_long", "split_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "An existing warrant/right public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Name recorded by the user for this warrant or right." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Total strike consideration for physical delivery, or actual gross cash settlement in option currency. Zero for expiry/transfer/split; no inferred contract factor.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "warrant" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "to_broker_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "split_numerator": { "type": "string", "maxLength": 40 }, "split_denominator": { "type": "string", "maxLength": 40 }, "delivery_action": { "type": "string", "enum": [ "buy", "sell", "short_sell", "short_cover" ], "description": "Required only for physical delivery: exercise_call/assign_put require buy or short_cover; exercise_put/assign_call require sell or short_sell. No automatic choice." }, "targets": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/FreshOptionsDeliveryTargetInput" } }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "allOf": [ { "if": { "properties": { "action": { "enum": [ "exercise_call", "exercise_put", "assign_call", "assign_put" ] } }, "required": [ "action" ] }, "then": { "required": [ "quantity", "principal", "delivery_action", "targets" ] } }, { "if": { "properties": { "action": { "enum": [ "exercise_call", "assign_put" ] } }, "required": [ "action" ] }, "then": { "properties": { "delivery_action": { "enum": [ "buy", "short_cover" ] } } } }, { "if": { "properties": { "action": { "enum": [ "exercise_put", "assign_call" ] } }, "required": [ "action" ] }, "then": { "properties": { "delivery_action": { "enum": [ "sell", "short_sell" ] } } } }, { "if": { "properties": { "action": { "enum": [ "expire_long", "expire_short", "cash_settle_long", "cash_settle_short", "transfer_long", "transfer_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "quantity" ] } }, { "if": { "properties": { "action": { "enum": [ "cash_settle_long", "cash_settle_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "principal" ] } }, { "if": { "properties": { "action": { "enum": [ "transfer_long", "transfer_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "to_broker_public_id" ] } }, { "if": { "properties": { "action": { "enum": [ "split_long", "split_short" ] } }, "required": [ "action" ] }, "then": { "required": [ "split_numerator", "split_denominator" ] } } ] }, "FreshWarrantsValuationInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "instrument_public_id", "action", "fiscal_year_public_id", "market_price", "quote_basis" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "Existing option public identity in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "valuation_long", "valuation_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only when option and administration currencies differ. Converts the actual year-end market value; no purchase-date rate is silently reused." }, "quantity": { "type": "string", "description": "Derived zero compatibility value in normalized source input. Valuation applies to the actual open quantity proved at the fiscal-year end; users do not supply a quantity.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required for nonzero net cash. For exactly zero net consideration no settlement fields apply: status is none and inactive settlement fields are ignored, in both website and API." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "market_price": { "type": "string", "maxLength": 40, "description": "Nonnegative entered quote per complete contract or per underlying unit as explicitly selected in quote_basis. No source, quotation date or factor is guessed." }, "instrument_kind": { "type": "string", "const": "warrant" }, "quote_basis": { "type": "string", "enum": [ "per_contract", "per_underlying_unit" ] }, "contract_factor": { "type": "string", "maxLength": 40, "description": "Explicit positive decimal factor, required only for per_underlying_unit; prohibited for per_contract. No default." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Warrant/right valuation input through the shared Broker financial contract. Exact quantities, weighted average cost and actual cash movements. No inferred contract factor, tax exemption or cost-neutral qualification.", "allOf": [ { "if": { "properties": { "quote_basis": { "const": "per_underlying_unit" } }, "required": [ "quote_basis" ] }, "then": { "required": [ "contract_factor" ] } }, { "if": { "properties": { "quote_basis": { "const": "per_contract" } }, "required": [ "quote_basis" ] }, "then": { "not": { "required": [ "contract_factor" ] } } } ] }, "FreshWarrantsConversionInput": { "type": "object", "additionalProperties": false, "description": "Warrant/right conversion input through the shared Broker financial contract. Exact quantities, weighted average cost and actual cash movements. No inferred contract factor, tax exemption or cost-neutral qualification.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "targets" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "conversion_long", "conversion_short", "exchange_long", "exchange_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A fund public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Name recorded by the user for this warrant or right." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "warrant" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FreshWarrantsTargetInput" } }, "qualification_reference": { "type": "string", "maxLength": 255 }, "exchange_cash_direction": { "type": "string", "enum": [ "receive", "pay" ] }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshWarrantsDistributionInput": { "type": "object", "additionalProperties": false, "description": "Warrant/right distribution input through the shared Broker financial contract. Exact quantities, weighted average cost and actual cash movements. No inferred contract factor, tax exemption or cost-neutral qualification.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "stock_distribution_received" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A fund public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Name recorded by the user for this warrant or right." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "warrant" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "distribution_value": { "type": "string", "maxLength": 40, "description": "Required for stock distribution, nonnegative gross value in base currency. Unknown for cash dividend." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshWarrantsTargetInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "maxLength": 26, "description": "Existing target public identity, or new. A new identity is materialized once under the same atomic confirmation." }, "instrument_name": { "type": "string", "maxLength": 255, "description": "Name recorded by the user for this warrant or right." }, "instrument_kind": { "type": "string", "const": "warrant" }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ] }, "instrument_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "cost_percentage": { "type": "string", "maxLength": 40, "description": "Cost-continuation only; declared allocation; all targets must total exactly 100." }, "base_value": { "type": "string", "maxLength": 40, "description": "Exchange only; explicitly declared nonnegative new cost/carrying in base currency." } }, "description": "Warrant/right target input through the shared Broker financial contract. Exact quantities, weighted average cost and actual cash movements. No inferred contract factor, tax exemption or cost-neutral qualification.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshBondsTargetInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "maxLength": 26, "description": "Existing target public identity, or new. A new identity is materialized once under the same atomic confirmation." }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_kind": { "type": "string", "enum": [ "bond", "share" ], "description": "Explicit bond or share kind for a new target. Omission retains the existing Bonds API contract (bond); a new share requires share. An existing target uses its recorded kind; any supplied kind must match." }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ] }, "instrument_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "cost_percentage": { "type": "string", "maxLength": 40, "description": "Cost-continuation only; declared allocation; all targets must total exactly 100." }, "base_value": { "type": "string", "maxLength": 40, "description": "Exchange only; explicitly declared nonnegative new cost/carrying in base currency." } }, "description": "Received or retained bond/share targets in a bond conversion or exchange. New targets require name, listing and currency. Positive exact quantities and the explicit continuation percentage or new exchange basis are required. Separate bond interest is excluded from target cost.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "BrokerCashInput": { "type": "object", "description": "Cash interest received or paid and standalone broker costs. Currency and actual gross amount are explicit. No investment, position, contract, listing or cost basis is created. Actual tax withheld from received interest is recorded separately using the existing explicit tax_claim/tax_expense choice, without assumed recoverability or exemption. Fees, FX, partial/mixed-currency payments, no-cash net zero, order, joint corrections and minimal tombstones use the same financial source contract. Additional fees and withholding apply only to received interest. For interest paid and standalone costs, principal is the full amount and fees/withholding must be zero or omitted; inactive website fields are disabled.", "required": [ "instrument_kind", "broker_public_id", "action", "trade_date", "currency_code", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "broker_interest_received", "broker_interest_paid", "broker_fees" ] }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "null", "description": "Money-only sources have no investment instrument. Omit this field on initial input; stored input contains null." }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "enum": [ "0" ], "description": "No instrument quantity. Omit on input; normalized source facts carry 0." }, "principal": { "type": "string", "description": "Actual gross interest or standalone cost, excluding optional fees and withholding, in currency_code. Monetary precision follows the currency; excess decimals are rejected without rounding.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional additional costs on received interest only, in fee_currency_code or currency_code when omitted. Blank or null means zero. For paid interest and standalone broker costs, record the full amount in principal; nonzero fees are rejected. No investment acquisition basis is created. Currency precision is validated without rounding. Stored paid-interest and standalone-cost sources omit this inapplicable field; the calculation uses zero without storing it. Received-interest and security sources retain their existing contract.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Actual tax withheld from received interest in currency_code. Blank or null means zero. Paid interest and standalone costs require zero or omitted withholding. Nonzero withholding requires an explicit treatment; no recovery or exemption is inferred. Currency precision is validated without rounding.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "cash" ] }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false }, "BrokerFuturesCountInput": { "type": "object", "description": "Future contract count source. No nominal amount, market quote, margin or GAK. Principal must be absent or zero. Opening long/short specifies existing contracts on the first fiscal year start without an opening-balance journal. Fees are separate actual expenses and support their own currency and Bank payments. Corrections and minimal deletion tombstones follow the shared atomic Broker contract.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "future_open_long", "future_close_long", "future_open_short", "future_close_short", "future_opening_long", "future_opening_short" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Public identity of a future contract in this administration, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Inapplicable: absent or zero only. Do not enter notional contract value.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Actual fees are posted as separate expenses and never create or change a contract cost basis. Monetary total in fee_currency_code, or daily settlement currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Fees can have their own currency and actual Bank payment. There is no fee-treatment selection. Opening contract specifications do not accept fees.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Inapplicable: absent, blank or zero only.", "maxLength": 40 }, "withholding_treatment": { "type": "null" }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "future" ] }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false }, "BrokerFuturesDailyInput": { "type": "object", "description": "Future contract daily actual gain/loss. Result date determines the claim; actual payment date determines Bank movement. Zero daily results are valid without fictitious journals; quantity must be absent or zero. Fees are separate actual expenses and support their own currency and Bank payments. Corrections and minimal deletion tombstones follow the shared atomic Broker contract.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "futures_gain", "futures_loss" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Public identity of a future contract in this administration, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "const": "0" }, "principal": { "type": "string", "description": "Actual daily gain or loss excluding fees, in the contract daily settlement currency. Enter a nonnegative amount; action determines gain or loss. Zero daily results are allowed. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. This amount is neither notional contract value nor acquisition cost and does not change the contract count.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Actual fees are posted as separate expenses and never create or change a contract cost basis. Monetary total in fee_currency_code, or daily settlement currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Fees can have their own currency and actual Bank payment. There is no fee-treatment selection. Opening contract specifications do not accept fees.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Inapplicable: absent, blank or zero only.", "maxLength": 40 }, "withholding_treatment": { "type": "null" }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "future" ] }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false }, "FreshParticipationsTradeInput": { "type": "object", "description": "Direct participation acquisition or disposal. Weighted-average historical cost and fiscal carrying value remain separate. Acquisition fees are in cost; disposal fees reduce proceeds. Explicit exemption facts and non-deductible acquisition/disposal costs are reported separately without computing a corporate income tax return. Bank/FX, review and all historical corrections share the established atomic contract.", "required": [ "instrument_kind", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "null", "description": "Direct participation; omit or supply null. No fictitious broker or money account. Actual payments alone refer to Bank accounts." }, "action": { "type": "string", "enum": [ "buy", "sell" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Participation public identity, or new for acquisition/opening.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "participation" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage. Required also for a new holding of a previously fully disposed instrument; a past holding is never reused as a qualification default." }, "participation_relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role. Required also for a new holding of a previously fully disposed instrument; a past holding is never reused as a qualification default." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "currency_code", "participation_exempt", "participation_relationship" ] } } ] }, "FreshParticipationsOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_kind", "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "broker_public_id": { "type": "null", "description": "Direct participation; omit or supply null. No fictitious broker or money account. Actual payments alone refer to Bank accounts." }, "instrument_public_id": { "type": "string", "description": "Participation public identity, or new for acquisition/opening.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "instrument_kind": { "type": "string", "const": "participation" }, "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage. Required also for a new holding of a previously fully disposed instrument; a past holding is never reused as a qualification default." }, "participation_relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role. Required also for a new holding of a previously fully disposed instrument; a past holding is never reused as a qualification default." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Specification of the existing opening balance, on the actual first fiscal-year start. No new journal or payment. Explicit participation relationship and exemption apply.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "currency_code", "participation_exempt", "participation_relationship" ] } } ] }, "FreshParticipationsIncomeInput": { "type": "object", "description": "Participation dividend and actual withholding, without automatic exemption of withholding tax. When dated reserves remain, supply one allocation for every active reserve, including zero, and evidence. Previously taxed benefits reduce carrying value and release the taxed reserve into taxable result; untaxed reserves remain separately identified. In-kind dividend increases the existing participation quantity and basis by the explicit nonnegative distribution_value in administration currency. Principal is only actual accompanying cash, zero when absent. Existing dated reserve allocations apply to cash plus in-kind gross value; no fictional bank payment.", "required": [ "instrument_kind", "action", "trade_date", "instrument_public_id", "principal" ], "properties": { "broker_public_id": { "type": "null", "description": "Direct participation; omit or supply null. No fictitious broker or money account. Actual payments alone refer to Bank accounts." }, "action": { "type": "string", "enum": [ "participation_dividend_received", "participation_stock_distribution_received" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Participation public identity. No new identity for this action.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "participation" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage." }, "participation_relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role." }, "reserve_allocations": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "reserve_public_id", "amount" ], "properties": { "reserve_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "amount": { "type": "string", "maxLength": 40, "description": "Signed release attributed to this dated reserve, including an explicit zero. Must have the reserve direction and fit the remaining reserve. In administration currency at currency precision; no rounding of entered amounts." } } } }, "tax_evidence": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Explicit substantiation for the established fiscal value, transition, liquidation or attribution; no automatic fiscal determination." }, "distribution_value": { "type": "string", "maxLength": 40, "description": "Required for stock distribution, nonnegative gross value in base currency. Unknown for cash dividend." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." }, "withholding_country_code": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Optional source withholding country from the existing application Countries list. Omitted/null remains unknown; never inferred from ISIN or a tax treatment." }, "dividend_payment_kind": { "type": [ "string", "null" ], "enum": [ "dividend", "substitute", "unknown", null ], "description": "Optional source classification. Descriptive only; actual gross/tax amounts and explicitly selected tax treatment are unchanged." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "action": { "const": "participation_stock_distribution_received" } }, "required": [ "action" ] }, "then": { "required": [ "quantity", "distribution_value" ] } } ] }, "FreshParticipationsEventInput": { "type": "object", "description": "Explicit capital contribution, capital return, liquidation distribution or completion. Existing units are preserved until final liquidation; no automatic fiscal loss deduction. Attribution fields apply only to capital-return/liquidation-distribution actions with active reserves; liquidation basis/loss fields apply only to liquidation. Unexpected action-specific fields are rejected.", "required": [ "instrument_kind", "action", "trade_date", "instrument_public_id", "principal" ], "properties": { "broker_public_id": { "type": "null", "description": "Direct participation; omit or supply null. No fictitious broker or money account. Actual payments alone refer to Bank accounts." }, "action": { "type": "string", "enum": [ "participation_contribution", "participation_capital_return", "participation_liquidation_distribution", "participation_liquidation" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Participation public identity. No new identity for this action.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "const": "0" }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "participation" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage." }, "participation_relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role." }, "reserve_allocations": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "reserve_public_id", "amount" ], "properties": { "reserve_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "amount": { "type": "string", "maxLength": 40, "description": "Signed release attributed to this dated reserve, including an explicit zero. Must have the reserve direction and fit the remaining reserve. In administration currency at currency precision; no rounding of entered amounts." } } } }, "tax_evidence": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Explicit substantiation for the established fiscal value, transition, liquidation or attribution; no automatic fiscal determination." }, "fiscal_basis": { "type": "string", "maxLength": 40, "description": "Established sacrificed tax basis for liquidation; not the accounting carrying value In administration currency at currency precision; no rounding of entered amounts." }, "total_liquidation_distributions": { "type": "string", "maxLength": 40, "description": "All established liquidation distributions including this source; may not omit previously entered liquidation distributions In administration currency at currency precision; no rounding of entered amounts." }, "deductible_loss": { "type": "string", "maxLength": 40, "description": "Explicit assessed deductible loss, between zero and the possible loss In administration currency at currency precision; no rounding of entered amounts." }, "deduction_year_public_id": { "type": [ "string", "null" ], "minLength": 26, "maxLength": 26, "description": "Required for positive deductible loss; explicit administration fiscal year, ending no earlier than liquidation. Closed fiscal results are protected." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "action": { "const": "participation_liquidation" } }, "required": [ "action" ] }, "then": { "required": [ "fiscal_basis", "total_liquidation_distributions", "deductible_loss", "tax_evidence" ] } } ] }, "FreshParticipationsTransitionInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_kind", "action", "instrument_public_id", "trade_date", "participation_exempt", "transition_value", "reserve_amount", "tax_evidence" ], "properties": { "instrument_kind": { "type": "string", "const": "participation" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "null", "description": "Direct participation; omit or supply null. No fictitious broker or money account. Actual payments alone refer to Bank accounts." }, "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "trade_date": { "type": "string", "format": "date" }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "quantity": { "type": "string", "const": "0" }, "principal": { "type": "string", "const": "0" }, "fees": { "type": "string", "const": "0" }, "withholding": { "type": "string", "const": "0" }, "withholding_treatment": { "type": "null" }, "settlement_status": { "type": "string", "const": "none" }, "settlements": { "type": "array", "maxItems": 0 }, "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage." }, "participation_relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role." }, "action": { "type": "string", "const": "participation_tax_status" }, "transition_value": { "type": "string", "maxLength": 40, "description": "Established value immediately before the dated exemption transition In administration currency at currency precision; no rounding of entered amounts." }, "reserve_amount": { "type": "string", "maxLength": 40, "description": "Explicit signed value minus prior fiscal carrying; must exactly close In administration currency at currency precision; no rounding of entered amounts." }, "tax_evidence": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Explicit substantiation for the established fiscal value, transition, liquidation or attribution; no automatic fiscal determination." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Actual transition into or out of participation exemption, distinct from correcting an incorrectly entered original fact. Prior periods remain separately attributable. Taxed reserve is a GL balance; untaxed reserve is source-based fiscal metadata. No cash or price conversion." }, "FreshParticipationsValuationInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_kind", "action", "instrument_public_id", "fiscal_year_public_id" ], "properties": { "instrument_kind": { "type": "string", "const": "participation" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "null", "description": "Direct participation; omit or supply null. No fictitious broker or money account. Actual payments alone refer to Bank accounts." }, "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "trade_date": { "type": "string", "format": "date" }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "quantity": { "type": "string", "const": "0" }, "principal": { "type": "string", "const": "0" }, "fees": { "type": "string", "const": "0" }, "withholding": { "type": "string", "const": "0" }, "withholding_treatment": { "type": "null" }, "settlement_status": { "type": "string", "const": "none" }, "settlements": { "type": "array", "maxItems": 0 }, "action": { "type": "string", "const": "valuation_long" }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "fiscal_carrying": { "type": "string", "maxLength": 40, "description": "Established nonexempt fiscal carrying value In administration currency at currency precision; no rounding of entered amounts." }, "tax_evidence": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Explicit substantiation for the established fiscal value, transition, liquidation or attribution; no automatic fiscal determination." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Date follows the chosen fiscal year actual end, including broken years. Exempt participation retains its cost-based fiscal basis, including documented transitions and attributions. Nonexempt participation requires established fiscal_carrying and evidence; no free policy or automatic ordinary-shares impairment. No invented market quote, listing or conversion." }, "FreshParticipationsTargetInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "maxLength": 26, "description": "Existing target public identity, or new. A new identity is materialized once under the same atomic confirmation." }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_kind": { "type": "string", "const": "participation" }, "instrument_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "cost_percentage": { "type": "string", "maxLength": 40, "description": "Cost-continuation only; declared allocation; all targets must total exactly 100." }, "base_value": { "type": "string", "maxLength": 40, "description": "Exchange only; explicitly declared nonnegative new cost/carrying in base currency." }, "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage. Required also for a new holding of a previously fully disposed instrument; a past holding is never reused as a qualification default." }, "participation_relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role. Required also for a new holding of a previously fully disposed instrument; a past holding is never reused as a qualification default." } }, "description": "Explicit received/retained participation, units and basis allocation or new consideration. Continuity carries the dated reserves; it does not infer exemption or neutrality. A new participation needs name, currency, relationship and exemption.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "currency_code", "participation_exempt", "participation_relationship" ] } } ] }, "FreshParticipationsConversionInput": { "type": "object", "additionalProperties": false, "description": "Participation continuation or exchange with explicit participation targets. Continuity needs qualification_reference and exact 100% allocation and same established exemption regime; transfers tax reserves without fictitious disposal. Exchange uses declared new values and actual cash and releases the disposed share of reserves. Linked target corrections are reviewed and saved together. Cost continuity carries the converted share of earlier liquidation distributions using the same explicitly confirmed basis percentages, with exact total closure.", "required": [ "instrument_kind", "action", "trade_date", "instrument_public_id", "quantity", "targets" ], "properties": { "broker_public_id": { "type": "null", "description": "Direct participation; omit or supply null. No fictitious broker or money account. Actual payments alone refer to Bank accounts." }, "action": { "type": "string", "enum": [ "conversion_long", "exchange_long" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Participation public identity. No new identity for this action.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "participation" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FreshParticipationsTargetInput" } }, "qualification_reference": { "type": "string", "maxLength": 255 }, "exchange_cash_direction": { "type": "string", "enum": [ "receive", "pay" ] }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage." }, "participation_relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshParticipationsFacts": { "type": "object", "required": [ "data", "needs_order" ], "properties": { "needs_order": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "required": [ "participation_exempt", "relationship", "reserves", "carrying", "cost", "quantity", "liquidation_distributions", "liquidation_distributions_exact" ], "properties": { "participation_exempt": { "type": "string", "enum": [ "yes", "no" ], "description": "Explicit applicability of participation exemption; never inferred from the company name, broker or holding percentage." }, "relationship": { "type": "string", "enum": [ "group", "related", "other" ], "description": "Explicit group company, other related company or other participation; selects the corresponding established accounting role." }, "reserves": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "required": [ "kind", "date", "amount", "amount_exact" ], "properties": { "kind": { "type": "string", "enum": [ "taxed", "untaxed" ] }, "date": { "type": "string", "format": "date" }, "amount": { "type": "string" }, "amount_exact": { "type": "string" } }, "additionalProperties": false } }, { "type": "array", "maxItems": 0 } ], "description": "Reserve identities map to their dated facts. No remaining reserves uses the existing empty-array JSON representation." }, "carrying": { "type": "string" }, "cost": { "type": "string" }, "quantity": { "type": "string", "description": "Exact held quantity immediately before the proposed source in the real dated order. Zero, or no prior source, identifies a new holding requiring explicit exemption and relationship on acquisition." }, "liquidation_distributions": { "type": "string", "description": "Previously recorded liquidation distributions for the remaining held portion, including explicit continuation allocations; administration currency." }, "liquidation_distributions_exact": { "type": "string", "description": "Exact retained distribution history amount in administration currency." } }, "additionalProperties": false } }, "additionalProperties": false }, "FreshTurbosTradeInput": { "type": "object", "description": "Turbo securities through the shared Broker contract. A purchased Turbo Long or Turbo Short is an owned security. Short selling and liability positions are not supported for turbos. Weighted average cost includes acquisition fees; financing already embedded in the price is not posted again. No leverage/stop-loss/underlying calculation or CFD fallback. Actual gross total per recorded trade; fees and withholding, separate fee currencies and actual partial settlements share the existing monetary contract.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "buy", "sell" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A turbo public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "turbo" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshTurbosOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A turbo public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "instrument_kind": { "type": "string", "const": "turbo" }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Turbo securities through the shared Broker contract. A purchased Turbo Long or Turbo Short is an owned security. Short selling and liability positions are not supported for turbos. Weighted average cost includes acquisition fees; financing already embedded in the price is not posted again. No leverage/stop-loss/underlying calculation or CFD fallback. Specifies the existing opening balance without a second journal.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "instrument_listing", "currency_code" ] } } ] }, "FreshTurbosEventInput": { "type": "object", "additionalProperties": false, "description": "Turbo securities through the shared Broker contract. A purchased Turbo Long or Turbo Short is an owned security. Short selling and liability positions are not supported for turbos. Weighted average cost includes acquisition fees; financing already embedded in the price is not posted again. No leverage/stop-loss/underlying calculation or CFD fallback. Existing security only. cash_settle_long closes the supplied quantity for an explicitly entered nonnegative total residual value, including zero. Transfers need quantity and a distinct destination; splits need an explicit positive ratio and apply to all owned units across depots with quantity zero. Fees and actual settlements remain available.", "required": [ "broker_public_id", "action", "trade_date", "instrument_public_id" ], "properties": { "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "transfer_long", "split_long", "cash_settle_long" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "A turbo public identity in this administration.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_listing": { "type": "string", "enum": [ "listed", "unlisted" ], "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "const": "turbo" }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "to_broker_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "split_numerator": { "type": "string", "maxLength": 40 }, "split_denominator": { "type": "string", "maxLength": 40 }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "allOf": [ { "if": { "properties": { "action": { "enum": [ "cash_settle_long" ] } }, "required": [ "action" ] }, "then": { "required": [ "quantity", "principal" ] } }, { "if": { "properties": { "action": { "enum": [ "transfer_long" ] } }, "required": [ "action" ] }, "then": { "required": [ "quantity", "to_broker_public_id" ] } }, { "if": { "properties": { "action": { "enum": [ "split_long" ] } }, "required": [ "action" ] }, "then": { "required": [ "split_numerator", "split_denominator" ] } } ] }, "FreshTurbosValuationInput": { "type": "object", "additionalProperties": false, "required": [ "broker_public_id", "instrument_public_id", "action", "fiscal_year_public_id", "market_price" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "string", "description": "Public identity of an active Bank account in this administration.", "maxLength": 26 }, "instrument_public_id": { "type": "string", "description": "A turbo public identity in this administration.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "valuation_long" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only when instrument and administration currencies differ. Converts native net consideration on trade date. Components round cumulatively to the exact converted net. Positive native amounts that convert to zero remain represented." }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required for nonzero net cash. For exactly zero net consideration no settlement fields apply: status is none and inactive settlement fields are ignored, in both website and API." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "market_price": { "type": "string", "maxLength": 40, "description": "Nonnegative price per registered fund unit, not a rounded transaction money amount. No quotation date, source or invented factor." }, "instrument_kind": { "type": "string", "const": "turbo" }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Turbo securities through the shared Broker contract. A purchased Turbo Long or Turbo Short is an owned security. Short selling and liability positions are not supported for turbos. Weighted average cost includes acquisition fees; financing already embedded in the price is not posted again. No leverage/stop-loss/underlying calculation or CFD fallback. User price per recorded turbo unit. Fiscal year end determines the date; no multiplier. Ordinary asset valuation policy preserves historical cost. Required FX uses the whole market value, not only the unit price." }, "BrokerSettingsBinding": { "type": "object", "additionalProperties": false, "required": [ "role", "currency", "label", "ledger_account", "revision", "used", "eligible", "accounts" ], "properties": { "role": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "ledger_account": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "type": "string", "format": "ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, { "type": "null" } ] }, "revision": { "type": [ "integer", "null" ] }, "used": { "type": "boolean" }, "eligible": { "type": "boolean" }, "accounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "type": "string", "format": "ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } } } } }, "BrokerSettingsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BrokerSettingsBinding" } } } }, "PutBrokerSettingsRequest": { "type": "object", "required": [ "mappings" ], "additionalProperties": false, "properties": { "mappings": { "type": "object", "minProperties": 1, "maxProperties": 500, "additionalProperties": { "type": "object", "required": [ "ledger_account_public_id", "expected_revision" ], "additionalProperties": false, "properties": { "ledger_account_public_id": { "type": [ "string", "null" ], "format": "ulid" }, "expected_revision": { "type": "integer", "minimum": 0 } } } } } }, "FreshCryptoTradeInput": { "type": "object", "description": "Crypto trade. Long holdings only. Amounts and prices are in the declared fiat quote currency. Uses the existing exact quantities, weighted purchase cost including fees, actual cash settlements and atomic historical correction.", "required": [ "action", "trade_date", "instrument_public_id", "quantity", "principal" ], "properties": { "broker_public_id": { "type": "null", "description": "Crypto holdings have no Bank account. Bank is selected only for an actual cash settlement." }, "action": { "type": "string", "enum": [ "buy", "sell" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Crypto coin public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision. Direct purchase costs increase the acquisition basis; short-opening costs reduce the received basis. Sale and cover costs are included in the net realized result. There is no fee-treatment selection. Short-opening costs above the gross proceeds leave a zero basis and recognize the excess as an immediate loss.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "crypto" ] }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "currency_code" ] } } ] }, "FreshCryptoOpeningInput": { "type": "object", "additionalProperties": false, "required": [ "action", "instrument_public_id", "quantity", "opening_cost", "opening_carrying" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "null", "description": "Crypto holdings have no Bank account. Bank is selected only for an actual cash settlement." }, "instrument_public_id": { "type": "string", "description": "Crypto coin public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "reference": { "type": [ "string", "null" ] }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "trade_date": { "type": "string", "format": "date", "description": "Derived from the start of the administration’s first fiscal year and existing opening balance. If supplied it must equal that date." }, "action": { "type": "string", "enum": [ "opening_long" ] }, "opening_cost": { "type": "string", "maxLength": 40, "description": "Total original historic cost in administration base currency, nonnegative, with its currency precision. Not a current quote." }, "opening_carrying": { "type": "string", "maxLength": 40, "description": "Total carrying value specified under the existing opening balance, in administration base currency, nonnegative. Remains distinct from historic cost and GAK." }, "principal": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "fees": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "0" }, "withholding_treatment": { "type": "null", "description": "Canonical stored non-applicable trade field; omit on new opening-position input." }, "settlement_status": { "type": "string", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "const": "none" }, "settlements": { "type": "array", "description": "Canonical stored non-applicable trade field; omit on new opening-position input.", "maxItems": 0 }, "instrument_kind": { "type": "string", "enum": [ "crypto" ] }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Crypto opening. Long holdings only. Amounts and prices are in the declared fiat quote currency. Uses the existing exact quantities, weighted purchase cost including fees, actual cash settlements and atomic historical correction.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "currency_code" ] } } ] }, "FreshCryptoValuationInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "action", "fiscal_year_public_id", "market_price" ], "properties": { "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "broker_public_id": { "type": "null", "description": "Crypto holdings have no Bank account. Bank is selected only for an actual cash settlement." }, "instrument_public_id": { "type": "string", "description": "Existing crypto coin public identity.", "maxLength": 26 }, "action": { "type": "string", "enum": [ "valuation_long" ], "maxLength": 255 }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required only when instrument and administration currencies differ. Converts native net consideration on trade date. Components round cumulatively to the exact converted net. Positive native amounts that convert to zero remain represented." }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required for nonzero net cash. For exactly zero net consideration no settlement fields apply: status is none and inactive settlement fields are ignored, in both website and API." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "market_price": { "type": "string", "maxLength": 40, "description": "Declared fiat market price per coin at fiscal year end. Book value is cost or lower market value." }, "instrument_kind": { "type": "string", "enum": [ "crypto" ] }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "description": "Crypto valuation. Long holdings only. Amounts and prices are in the declared fiat quote currency. Uses the existing exact quantities, weighted purchase cost including fees, actual cash settlements and atomic historical correction." }, "FreshCryptoConversionInput": { "type": "object", "additionalProperties": false, "description": "Crypto conversion. Long holdings only. Amounts and prices are in the declared fiat quote currency. Uses the existing exact quantities, weighted purchase cost including fees, actual cash settlements and atomic historical correction. The explicit value of incoming coins is their acquisition cost in administration currency. Released outgoing book value determines the trading result. No cost-continuation choice.", "required": [ "action", "trade_date", "instrument_public_id", "quantity", "targets", "exchange_cash_direction" ], "properties": { "broker_public_id": { "type": "null", "description": "Crypto holdings have no Bank account. Bank is selected only for an actual cash settlement." }, "action": { "type": "string", "enum": [ "exchange_long" ] }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Existing crypto coin public identity.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "description": "Actual gross consideration excluding fees and withholding. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "fees": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in fee_currency_code, or instrument currency when the fee currency is omitted. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding": { "type": [ "string", "null" ], "description": "Optional; blank or null means zero. Monetary total in instrument currency. At most the currency minor-unit decimal digits (EUR: 2); extra decimals cause a field validation error without rounding. Quantity and calculated average cost retain their own precision.", "maxLength": 40 }, "withholding_treatment": { "type": [ "string", "null" ], "enum": [ "tax_claim", "tax_expense", null ] }, "settlement_status": { "type": "string", "enum": [ "pending", "settled", "none" ], "maxLength": 255, "description": "Required when any native claim remains. Pending has no payments; settled has one or more actual payments, which may leave a remainder. Exactly zero net money in a single currency with no separate cost payments uses none and ignores inactive payment fields. Unlike currencies are never added or automatically treated as zero." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesSettlementInput" } }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "crypto" ] }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Recorded instrument-currency conversion on trade date, required for nonzero instrument-currency components when instrument and administration currencies differ. Fees in that same currency retain cumulative component rounding to the net total. Fees in another currency are excluded from this net total and use their own fee_fx only when required. No payment conversion is inferred from this rate. The website may reuse an explicitly entered whole-total base equivalent for a single full payment in base currency, without overwriting manual input. The actual editable account amount is still submitted explicitly; the API does not infer a payment amount." }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FreshCryptoTargetInput" } }, "exchange_cash_direction": { "type": "string", "enum": [ "receive", "pay" ] }, "fee_currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Supported fee currency. Optional for compatibility: omitted means instrument currency. The website initially follows the transaction currency until explicitly changed. No historical inputs are rewritten." }, "fee_fx": { "$ref": "#/components/schemas/FreshSharesFxInput", "description": "Required for nonzero fees only when fee currency differs from both instrument and administration currencies. Converts the actual fee total on trade date, with its own entered rate or base equivalent. Not accepted for zero fees, base-currency fees or fees already covered by trade_fx." }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } } }, "FreshCryptoTargetInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "quantity", "base_value" ], "properties": { "instrument_public_id": { "type": "string", "maxLength": 26, "description": "Crypto coin public identity, or new." }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_kind": { "type": "string", "enum": [ "crypto" ] }, "instrument_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "base_value": { "type": "string", "maxLength": 40, "description": "Exchange only; explicitly declared nonnegative new cost/carrying in base currency." } }, "description": "Received crypto coin and exact quantity, with its explicitly declared total value in administration currency. A new coin requires name and supported fiat quote currency.", "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_name", "currency_code" ] } } ] }, "FreshCryptoReceiptInput": { "type": "object", "description": "Approved zero-cost receipt of the actually received coin, including a staking reward in a different coin. Adds quantity with zero acquisition cost and no journal, payment or immediate income. Derived money fields may only be supplied with their exact canonical zero values. No staking lock or release workflow.", "required": [ "action", "trade_date", "instrument_public_id", "quantity" ], "properties": { "broker_public_id": { "type": "null", "description": "Crypto holdings have no Bank account. Bank is selected only for an actual cash settlement." }, "action": { "type": "string", "enum": [ "airdrop_received", "staking_reward_received" ] }, "trade_date": { "type": "string", "format": "date", "maxLength": 255 }, "instrument_public_id": { "type": "string", "description": "Crypto coin public identity, or new.", "maxLength": 26 }, "instrument_name": { "type": "string", "maxLength": 255 }, "instrument_identifier": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "string", "description": "Positive exact decimal (comma or point) or fraction, e.g. 0.125 or 1/3. The submitted quantity notation is retained in stored and reopened input; calculations use exact rational values without rounding. The complete input is limited to 257 characters, including separators.", "maxLength": 257 }, "principal": { "type": "string", "const": "0" }, "fees": { "type": "string", "const": "0" }, "withholding": { "type": "string", "const": "0" }, "withholding_treatment": { "type": "null" }, "settlement_status": { "type": "string", "const": "none" }, "settlements": { "type": "array", "maxItems": 0 }, "day_order": { "type": "string", "description": "Before/after an existing transaction on this date: before: or after:. Required when adding on an occupied date. Blank on correction keeps the original place when the date is unchanged. No numeric order or time." }, "reference": { "type": [ "string", "null" ] }, "instrument_kind": { "type": "string", "enum": [ "crypto" ] }, "command_id": { "type": "string", "description": "Optional compatibility field. The request Idempotency-Key supplies the authoritative command identity.", "maxLength": 255 }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "description": "Command-only chosen outgoing group counts and, only when ambiguous, signed actual result amounts. Exact source/position and cohort references are supplied by 422 details. No manual book-value targets." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "instrument_public_id": { "const": "new" } }, "required": [ "instrument_public_id" ] }, "then": { "required": [ "instrument_kind", "instrument_name", "currency_code" ] } } ] }, "BrokerGroupMemberInput": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "side", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "broker_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "side": { "type": "string", "enum": [ "long", "short" ] }, "quantity": { "type": "string", "maxLength": 257 } } }, "BrokerGroupInput": { "type": "object", "additionalProperties": false, "required": [ "name", "fiscal_year_public_id", "members" ], "properties": { "command_id": { "type": "string", "maxLength": 255 }, "revision": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "enum": [ "year_end" ] }, "name": { "type": "string", "maxLength": 150 }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "trade_date": { "type": "string", "format": "date" }, "predecessor_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupMemberInput" }, "minItems": 1, "maxItems": 40 }, "group_updates": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" }, "maxItems": 200 } }, "description": "Annual group after ordinary year-end values. Chosen positive counts, no defaults. A new group needs two positions, a continuation may retain one. Supported instruments: share, option, fund, bond, warrant, turbo, future and crypto. Participations retain their separate fiscal carrying-value workflow and cannot be group members. Date is the fiscal-year end. Corrections carry forward, no January reversal. Automatic uniquely proved count/result allocations; ambiguous allocations require actual choices." }, "BrokerGroupStoredInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "name", "fiscal_year_public_id", "trade_date", "members", "quantity_choices" ], "properties": { "command_id": { "type": "string", "maxLength": 255 }, "revision": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "enum": [ "year_end" ] }, "name": { "type": "string", "maxLength": 150 }, "fiscal_year_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "trade_date": { "type": "string", "format": "date" }, "predecessor_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupMemberInput" }, "minItems": 1, "maxItems": 40 }, "quantity_choices": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" } } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "name", "trade_date", "predecessor_public_id", "event_source_public_id", "members", "quantity_choices" ], "properties": { "command_id": { "type": "string", "maxLength": 255 }, "revision": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "enum": [ "event" ] }, "name": { "type": "string", "maxLength": 150 }, "trade_date": { "type": "string", "format": "date" }, "predecessor_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "members": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "side", "quantity" ], "properties": { "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "broker_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "side": { "type": "string", "enum": [ "long", "short" ] }, "quantity": { "type": "string" } } } }, "quantity_choices": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" } }, "event_source_public_id": { "type": "string", "description": "Public identity of the ordinary transaction or annual group selection that caused this derived mutation; not user input.", "minLength": 26, "maxLength": 26 } } } ] }, "BrokerGroupUpdate": { "type": "object", "additionalProperties": false, "required": [ "source_public_id", "position_key" ], "properties": { "source_public_id": { "type": "string", "description": "Ordinary source ULID or current for this command." }, "position_key": { "type": "string" }, "quantities": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "group_public_id", "cohort_id", "quantity" ], "properties": { "group_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "cohort_id": { "type": "string", "maxLength": 160 }, "quantity": { "type": "string", "maxLength": 257 } } } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "group_public_id", "result" ], "properties": { "group_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "result": { "type": "string", "maxLength": 100 } } } } }, "oneOf": [ { "required": [ "quantities" ], "not": { "required": [ "results" ] } }, { "required": [ "results" ], "not": { "required": [ "quantities" ] } } ], "description": "Command-only exact outgoing counts. Only an ambiguous real result requires signed amounts per group. No replacement financial targets or recursive inputs. Stored in derived group sources, never ordinary input." }, "BrokerGroupCalculation": { "type": "object", "additionalProperties": false, "required": [ "members", "allocations", "lines", "currency_code", "processed_transactions" ], "properties": { "members": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "side", "quantity", "economic_value", "target_book_value", "deferred_loss" ], "properties": { "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "broker_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "side": { "type": "string", "enum": [ "long", "short" ] }, "quantity": { "type": "string" }, "economic_value": { "type": "string", "description": "Derived from ordinary books and exact group allocation; never a manual target." }, "target_book_value": { "type": "string", "description": "Derived from ordinary books and exact group allocation; never a manual target." }, "deferred_loss": { "type": "string", "description": "Derived from ordinary books and exact group allocation; never a manual target." }, "name": { "type": "string" }, "instrument_kind": { "type": "string" }, "available_quantity": { "type": "string" }, "ordinary_cost": { "type": "string" }, "ordinary_book": { "type": "string" }, "valuation_overlay": { "type": "string" }, "overlay": { "type": "string" }, "other_group_adjustment": { "type": "string" }, "combined_position_book": { "type": "string" } } } }, "allocations": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "required": [ "member_key", "instrument_public_id", "side", "balance", "result", "amount", "sign" ], "properties": { "member_key": { "type": "string" }, "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "side": { "type": "string", "enum": [ "long", "short" ] }, "balance": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "currency_mode": { "type": "string" }, "normal_balance": { "type": "string" }, "reporting_classification_code": { "type": "string" } } }, "result": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "currency_mode": { "type": "string" }, "normal_balance": { "type": "string" }, "reporting_classification_code": { "type": "string" } } }, "amount": { "type": "string" }, "sign": { "type": "integer", "enum": [ -1, 1 ] } } } }, { "type": "array", "maxItems": 0 } ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } }, "currency_code": { "type": "string" }, "processed_transactions": { "type": "integer", "minimum": 0 }, "cohorts": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "side", "quantity", "origin_public_id" ], "properties": { "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "broker_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "side": { "type": "string", "enum": [ "long", "short" ] }, "quantity": { "type": "string" }, "origin_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "realized_result_role": { "type": "string" }, "closed_on": { "type": "string", "format": "date" } } } }, { "type": "array", "maxItems": 0 } ] }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "loss", "gain", "amount" ], "properties": { "kind": { "type": "string", "enum": [ "valuation", "deferred" ] }, "loss": { "type": "string" }, "gain": { "type": "string" }, "amount": { "type": "string" }, "component": { "type": "string" } } } }, "loss_packets": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "required": [ "source_public_id", "source_cohorts", "source_position", "quantity", "original_loss", "components", "carried", "pending", "closed", "eligible" ], "properties": { "source_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "source_cohorts": { "type": "array", "items": { "type": "string" } }, "source_position": { "type": "object", "additionalProperties": false, "required": [ "instrument_public_id", "side" ], "properties": { "instrument_public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "broker_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "side": { "type": "string", "enum": [ "long", "short" ] } } }, "source_result_role": { "type": "string" }, "quantity": { "type": "string" }, "original_loss": { "type": "string" }, "components": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "required": [ "carried", "pending", "closed", "eligible" ], "properties": { "carried": { "type": "string" }, "pending": { "type": "string" }, "closed": { "type": "string" }, "eligible": { "type": "array", "items": { "type": "string" } } } } }, { "type": "array", "maxItems": 0 } ] }, "carried": { "type": "string" }, "pending": { "type": "string" }, "closed": { "type": "string" }, "eligible": { "type": "array", "items": { "type": "string" } } } } }, { "type": "array", "maxItems": 0 } ] }, "support_allocation": { "type": "object", "additionalProperties": false, "required": [ "losses", "gains", "links", "total" ], "properties": { "losses": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "maxItems": 0 } ] }, "gains": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "maxItems": 0 } ] }, "links": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "maxItems": 0 } ] } }, { "type": "array", "maxItems": 0 } ] }, "total": { "type": "string" } } }, "year_facts": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "required": [ "side", "cost", "book", "market", "nominal_balance" ], "properties": { "realized_result_role": { "type": "string" }, "side": { "type": "string" }, "cost": { "type": "string" }, "book": { "type": "string" }, "market": { "type": "string" }, "nominal_balance": { "type": "boolean" }, "available_quantity": { "type": "string" }, "valuation_source_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "valuation_source_revision": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } } } }, { "type": "array", "maxItems": 0 } ] }, "event_allocation": { "type": "object", "additionalProperties": false, "required": [ "groups" ], "properties": { "groups": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "required": [ "amount", "choice", "mode" ], "properties": { "amount": { "type": "string" }, "choice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string" } } } }, { "type": "array", "maxItems": 0 } ] }, "outside": { "type": "string" }, "book_result": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } } } }, "ordinary_source_revision": { "type": "integer" } } }, "BrokerGroupChange": { "type": "object", "additionalProperties": false, "required": [ "public_id", "input", "calculation", "operation" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "input": { "anyOf": [ { "$ref": "#/components/schemas/BrokerGroupStoredInput" }, { "type": "null" } ] }, "calculation": { "anyOf": [ { "$ref": "#/components/schemas/BrokerGroupCalculation" }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "create", "update", "remove" ] }, "before_lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } }, "before_currency_code": { "type": "string" } } }, "BrokerGroupSource": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "removed", "journal_entry_public_id", "input", "calculation" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "revision": { "type": "integer", "minimum": 1 }, "removed": { "type": "boolean" }, "journal_entry_public_id": { "anyOf": [ { "type": "string", "minLength": 26, "maxLength": 26 }, { "type": "null" } ] }, "input": { "anyOf": [ { "$ref": "#/components/schemas/BrokerGroupStoredInput" }, { "type": "null" } ] }, "calculation": { "anyOf": [ { "$ref": "#/components/schemas/BrokerGroupCalculation" }, { "type": "null" } ] } }, "description": "Current source only. Deletion leaves identity/revision/actors/time and clears financial input/calculation/member links. Central financial audit is the sole archive; receipts contain only source/journal references." }, "BrokerGroupResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BrokerGroupSource" } } }, "BrokerGroupOverview": { "type": "object", "required": [ "data", "meta" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupSource" } }, "meta": { "type": "object", "required": [ "current_page", "last_page" ], "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" } } } } }, "BrokerGroupPreview": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "input", "plan", "confirmation_token", "can_confirm" ], "properties": { "input": { "$ref": "#/components/schemas/BrokerGroupInput" }, "plan": { "type": "object", "additionalProperties": false, "required": [ "public_id", "operation", "changes" ], "properties": { "public_id": { "type": "string", "minLength": 26, "maxLength": 26 }, "operation": { "type": "string", "enum": [ "create", "update", "remove" ] }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupChange" } } } }, "confirmation_token": { "type": "string" }, "can_confirm": { "type": "boolean" } } } } }, "LoanTermInput": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "due_on": { "type": [ "string", "null" ], "format": "date" }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." } }, "required": [ "principal", "interest" ] }, "LoanRegisterInput": { "type": "object", "additionalProperties": false, "properties": { "direction": { "enum": [ "borrowed", "lent" ] }, "name": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "contact_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "term_count": { "type": "integer", "minimum": 0 }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/LoanTermInput" } } }, "required": [ "direction", "name", "currency_code", "term_count" ] }, "LoanRegisterUpdate": { "type": "object", "description": "An explicit unused loan currency change also updates its dedicated principal and linked unpaid-interest accounts, preserving their identities, codes and RGS. Such an edit additionally requires ledger_accounts:write when these accounts are linked. Interest result stays in accounting currency. Ordinary name/contact/schedule edits require only loans:write. Used currencies/accounts retain the existing protections.", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 255 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "contact_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "term_count": { "type": "integer", "minimum": 0 }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/LoanTermInput" } }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "name", "currency_code", "revision", "term_count" ] }, "LoanAccountsInput": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "accounts": { "type": "object", "additionalProperties": false, "properties": { "principal": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "interest_balance": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "interest_result": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } }, "required": [] } }, "required": [ "revision", "accounts" ] }, "LoanAllocation": { "type": "object", "additionalProperties": false, "properties": { "term_public_id": { "$ref": "#/components/schemas/Ulid" }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." } }, "required": [ "term_public_id", "principal", "interest" ] }, "LoanFxInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "conversion_mode": { "const": "rate" }, "rate": { "type": "string", "maxLength": 40 } }, "required": [ "conversion_mode", "rate" ] }, { "type": "object", "additionalProperties": false, "properties": { "conversion_mode": { "const": "converted_amount" }, "converted_base_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Total principal plus interest converted into the administration currency." } }, "required": [ "conversion_mode", "converted_base_amount" ] } ] }, "LoanTransactionInput": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "funding", "payment", "interest", "capitalization" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "settled_interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Actual amount paid or received in the bank account currency." }, "loan_fx": { "$ref": "#/components/schemas/LoanFxInput" }, "term_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Optional single instalment choice for payment only. The explicit principal and full interest amounts are allocated to this instalment. Do not combine with nonempty allocations. Amounts remain required and may be adjusted for a partial payment. Ownership and current remaining capacity are checked during planning under the ordinary financial locks." }, "allocations": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/LoanAllocation" } }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Only for a new funding/payment cash source. Explicit relative placement against an authorized existing journal on the same real foreign-account day. Updates and non-cash kinds reject this field; an anchor on another date or account is invalid." } }, "required": [ "kind", "posting_date" ], "description": "Funding/payment requires principal and a bank account; payment/interest/capitalization requires interest. Payment/capitalization may explicitly settle previously accrued interest. Payment may choose term_public_id to allocate the entered amounts once, or use optional manual allocations for several instalments; other kinds prohibit both. The website copies the current remaining amounts only after an explicit instalment choice, excluding the edited transaction when preparing choices. API amounts remain explicit. A foreign loan requires an explicit loan_fx conversion of principal plus interest. A third-currency bank account requires its actual bank_amount. No schedule or interest is guessed." }, "LoanTransactionUpdate": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "funding", "payment", "interest", "capitalization" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "settled_interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Actual amount paid or received in the bank account currency." }, "loan_fx": { "$ref": "#/components/schemas/LoanFxInput" }, "term_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Optional single instalment choice for payment only. The explicit principal and full interest amounts are allocated to this instalment. Do not combine with nonempty allocations. Amounts remain required and may be adjusted for a partial payment. Ownership and current remaining capacity are checked during planning under the ordinary financial locks." }, "allocations": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/LoanAllocation" } }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "posting_date", "expected_revision" ] }, "LoanTransactionConfirm": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "funding", "payment", "interest", "capitalization" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "settled_interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Actual amount paid or received in the bank account currency." }, "loan_fx": { "$ref": "#/components/schemas/LoanFxInput" }, "term_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Optional single instalment choice for payment only. The explicit principal and full interest amounts are allocated to this instalment. Do not combine with nonempty allocations. Amounts remain required and may be adjusted for a partial payment. Ownership and current remaining capacity are checked during planning under the ordinary financial locks." }, "allocations": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/LoanAllocation" } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "posting_date", "state_hash" ] }, "LoanTransactionUpdateConfirm": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "funding", "payment", "interest", "capitalization" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "settled_interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Actual amount paid or received in the bank account currency." }, "loan_fx": { "$ref": "#/components/schemas/LoanFxInput" }, "term_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Optional single instalment choice for payment only. The explicit principal and full interest amounts are allocated to this instalment. Do not combine with nonempty allocations. Amounts remain required and may be adjusted for a partial payment. Ownership and current remaining capacity are checked during planning under the ordinary financial locks." }, "allocations": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/LoanAllocation" } }, "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "posting_date", "expected_revision", "state_hash" ] }, "LoanDeletePreviewInput": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "expected_revision" ] }, "LoanDeleteConfirmInput": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "expected_revision", "state_hash" ] }, "LoanTransaction": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "loan_public_id": { "$ref": "#/components/schemas/Ulid" }, "journal_entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer" }, "input": { "anyOf": [ { "$ref": "#/components/schemas/LoanTransactionInput" }, { "type": "null" } ] }, "removed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "public_id", "loan_public_id", "journal_entry_public_id", "revision", "input", "removed_at" ] }, "LoanTerm": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "due_on": { "type": [ "string", "null" ], "format": "date" }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "position": { "type": "integer" }, "paid_principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "paid_interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." } }, "required": [ "public_id", "position", "due_on", "principal", "interest", "paid_principal", "paid_interest" ] }, "Loan": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "direction": { "enum": [ "borrowed", "lent" ] }, "currency_code": { "type": "string" }, "contact_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "revision": { "type": "integer" }, "as_of": { "type": "string", "format": "date" }, "accounts": { "type": "object", "additionalProperties": false, "properties": { "principal": { "$ref": "#/components/schemas/Ulid" }, "interest_balance": { "$ref": "#/components/schemas/Ulid" }, "interest_result": { "$ref": "#/components/schemas/Ulid" } }, "required": [] }, "balances": { "type": "object", "additionalProperties": false, "properties": { "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest_balance": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "principal_base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the administration currency." }, "interest_balance_base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the administration currency." } }, "required": [ "principal", "interest_balance", "principal_base", "interest_balance_base" ] }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/LoanTerm" } } }, "required": [ "public_id", "name", "direction", "currency_code", "contact_public_id", "revision", "as_of", "accounts", "balances", "terms" ] }, "LoanPreview": { "type": "object", "required": [ "state_hash" ], "properties": { "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "valuation_journals": { "type": "array", "items": { "type": "object" }, "description": "Under the active periodic cash policy, all additional existing currency valuation journals belonging to this complete source proposal. They are confirmed atomically with the Loan journal; ordinary later cash sources remain unchanged." } }, "description": "Read-only financial proposal. Includes shared journal preview lines, balances_before, source input and kind; a deletion proposal contains removal identity/revision. Confirm the unchanged input and returned hash." }, "BankLoanInput": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "funding", "payment" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "principal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "settled_interest": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Exact decimal amount in the loan currency; use a string. Zero is allowed." }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,4})?$", "description": "Actual amount paid or received in the bank account currency." }, "loan_fx": { "$ref": "#/components/schemas/LoanFxInput" }, "term_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Optional single instalment choice for payment only. The explicit principal and full interest amounts are allocated to this instalment. Do not combine with nonempty allocations. Amounts remain required and may be adjusted for a partial payment. Ownership and current remaining capacity are checked during planning under the ordinary financial locks." }, "allocations": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/LoanAllocation" } }, "loan_public_id": { "$ref": "#/components/schemas/Ulid" } }, "required": [ "loan_public_id", "kind", "posting_date", "principal", "bank_account_public_id" ] }, "LoanSummary": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "direction": { "enum": [ "borrowed", "lent" ] }, "currency_code": { "type": "string" }, "revision": { "type": "integer" } }, "required": [ "public_id", "name", "direction", "currency_code", "revision" ] }, "CurrentAccountInterestPreviewRequest": { "type": "object", "additionalProperties": false, "properties": { "position_public_id": { "$ref": "#/components/schemas/Ulid" }, "income_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "method": { "enum": [ "manual", "calculated" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "receivable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "payable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "day_basis": { "enum": [ "365", "360", "actual" ] }, "fx_rate": { "type": "string", "description": "Positive accounting-currency units per one RC-currency unit. Required for foreign RC currency; prohibited for accounting currency." }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "position_public_id", "method", "posting_date", "description" ], "description": "One local ordinary manual journal; no automatic counterpart in another administration. Historical RC changes do not modify posted interest. Manual mode requires income and expense (0 allowed); calculated mode prohibits them and requires period, both annual rates and year basis. Interest accounts are required only for their positive native side. Calculated mode prohibits manual amounts; manual mode prohibits calculator rates and day basis. A movement counts from its posting date, both period dates count, and each side rounds once. Preview excludes the journal being edited. Unknown root properties and arrays in scalar fields are rejected.", "allOf": [ { "if": { "properties": { "method": { "const": "manual" } } }, "then": { "required": [ "income", "expense" ], "not": { "anyOf": [ { "required": [ "receivable_rate" ] }, { "required": [ "payable_rate" ] }, { "required": [ "day_basis" ] } ] } }, "else": { "required": [ "starts_on", "ends_on", "receivable_rate", "payable_rate", "day_basis" ], "not": { "anyOf": [ { "required": [ "income" ] }, { "required": [ "expense" ] } ] } } } ] }, "CurrentAccountInterestPostRequest": { "type": "object", "additionalProperties": false, "properties": { "position_public_id": { "$ref": "#/components/schemas/Ulid" }, "income_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "method": { "enum": [ "manual", "calculated" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "receivable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "payable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "day_basis": { "enum": [ "365", "360", "actual" ] }, "fx_rate": { "type": "string", "description": "Positive accounting-currency units per one RC-currency unit. Required for foreign RC currency; prohibited for accounting currency." }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "position_public_id", "method", "posting_date", "description", "state_hash" ], "description": "One local ordinary manual journal; no automatic counterpart in another administration. Historical RC changes do not modify posted interest. Manual mode requires income and expense (0 allowed); calculated mode prohibits them and requires period, both annual rates and year basis. Interest accounts are required only for their positive native side. Calculated mode prohibits manual amounts; manual mode prohibits calculator rates and day basis. A movement counts from its posting date, both period dates count, and each side rounds once. Preview excludes the journal being edited. Unknown root properties and arrays in scalar fields are rejected.", "allOf": [ { "if": { "properties": { "method": { "const": "manual" } } }, "then": { "required": [ "income", "expense" ], "not": { "anyOf": [ { "required": [ "receivable_rate" ] }, { "required": [ "payable_rate" ] }, { "required": [ "day_basis" ] } ] } }, "else": { "required": [ "starts_on", "ends_on", "receivable_rate", "payable_rate", "day_basis" ], "not": { "anyOf": [ { "required": [ "income" ] }, { "required": [ "expense" ] } ] } } } ] }, "CurrentAccountInterestEditPreviewRequest": { "type": "object", "additionalProperties": false, "properties": { "position_public_id": { "$ref": "#/components/schemas/Ulid" }, "income_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "method": { "enum": [ "manual", "calculated" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "receivable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "payable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "day_basis": { "enum": [ "365", "360", "actual" ] }, "fx_rate": { "type": "string", "description": "Positive accounting-currency units per one RC-currency unit. Required for foreign RC currency; prohibited for accounting currency." }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "position_public_id", "method", "posting_date", "description", "expected_revision" ], "description": "One local ordinary manual journal; no automatic counterpart in another administration. Historical RC changes do not modify posted interest. Manual mode requires income and expense (0 allowed); calculated mode prohibits them and requires period, both annual rates and year basis. Interest accounts are required only for their positive native side. Calculated mode prohibits manual amounts; manual mode prohibits calculator rates and day basis. A movement counts from its posting date, both period dates count, and each side rounds once. Preview excludes the journal being edited. Unknown root properties and arrays in scalar fields are rejected.", "allOf": [ { "if": { "properties": { "method": { "const": "manual" } } }, "then": { "required": [ "income", "expense" ], "not": { "anyOf": [ { "required": [ "receivable_rate" ] }, { "required": [ "payable_rate" ] }, { "required": [ "day_basis" ] } ] } }, "else": { "required": [ "starts_on", "ends_on", "receivable_rate", "payable_rate", "day_basis" ], "not": { "anyOf": [ { "required": [ "income" ] }, { "required": [ "expense" ] } ] } } } ] }, "CurrentAccountInterestEditRequest": { "type": "object", "additionalProperties": false, "properties": { "position_public_id": { "$ref": "#/components/schemas/Ulid" }, "income_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "method": { "enum": [ "manual", "calculated" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "receivable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "payable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "day_basis": { "enum": [ "365", "360", "actual" ] }, "fx_rate": { "type": "string", "description": "Positive accounting-currency units per one RC-currency unit. Required for foreign RC currency; prohibited for accounting currency." }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "position_public_id", "method", "posting_date", "description", "expected_revision", "state_hash" ], "description": "One local ordinary manual journal; no automatic counterpart in another administration. Historical RC changes do not modify posted interest. Manual mode requires income and expense (0 allowed); calculated mode prohibits them and requires period, both annual rates and year basis. Interest accounts are required only for their positive native side. Calculated mode prohibits manual amounts; manual mode prohibits calculator rates and day basis. A movement counts from its posting date, both period dates count, and each side rounds once. Preview excludes the journal being edited. Unknown root properties and arrays in scalar fields are rejected.", "allOf": [ { "if": { "properties": { "method": { "const": "manual" } } }, "then": { "required": [ "income", "expense" ], "not": { "anyOf": [ { "required": [ "receivable_rate" ] }, { "required": [ "payable_rate" ] }, { "required": [ "day_basis" ] } ] } }, "else": { "required": [ "starts_on", "ends_on", "receivable_rate", "payable_rate", "day_basis" ], "not": { "anyOf": [ { "required": [ "income" ] }, { "required": [ "expense" ] } ] } } } ] }, "CurrentAccountInterestSavedInput": { "type": "object", "additionalProperties": false, "properties": { "position_public_id": { "$ref": "#/components/schemas/Ulid" }, "income_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expense_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "method": { "enum": [ "manual", "calculated" ] }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "receivable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "payable_rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Annual percentage as an exact decimal string. Zero is allowed; percentage precision is independent of currency precision." }, "day_basis": { "enum": [ "365", "360", "actual" ] }, "fx_rate": { "type": "string", "description": "Positive accounting-currency units per one RC-currency unit. Required for foreign RC currency; prohibited for accounting currency." } }, "required": [ "position_public_id", "method", "posting_date", "description" ], "description": "One local ordinary manual journal; no automatic counterpart in another administration. Historical RC changes do not modify posted interest. Manual mode requires income and expense (0 allowed); calculated mode prohibits them and requires period, both annual rates and year basis. Interest accounts are required only for their positive native side. Calculated mode prohibits manual amounts; manual mode prohibits calculator rates and day basis. A movement counts from its posting date, both period dates count, and each side rounds once. Preview excludes the journal being edited. Unknown root properties and arrays in scalar fields are rejected." }, "CurrentAccountInterestCalculationSummary": { "type": "object", "additionalProperties": false, "properties": { "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "opening_balance": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "closing_balance": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "days": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "income", "expense", "opening_balance", "closing_balance", "days", "state_hash" ] }, "CurrentAccountInterestCalculation": { "type": "object", "additionalProperties": false, "properties": { "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "opening_balance": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "closing_balance": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "days": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "segments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "days": { "type": "integer", "minimum": 1 }, "balance": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "rate": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "basis": { "type": "integer", "enum": [ 360, 365, 366 ] }, "kind": { "enum": [ "income", "expense" ] } }, "required": [ "starts_on", "ends_on", "days", "balance", "rate", "basis", "kind" ] } } }, "required": [ "income", "expense", "opening_balance", "closing_balance", "days", "state_hash", "segments" ] }, "CurrentAccountInterestPreview": { "type": "object", "additionalProperties": false, "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "calculation": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountInterestCalculation" }, { "type": "null" } ] }, "income": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "expense": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact decimal string; amounts use the RC currency precision. Zero is allowed. No binary floating-point values." }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "journal": { "$ref": "#/components/schemas/JournalFxPreview" } }, "required": [ "state_hash", "calculation", "income", "expense", "currency_code", "journal" ] }, "CurrentAccountInterestPreviewResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountInterestPreview" } }, "required": [ "data" ] }, "CurrentAccountInterest": { "type": "object", "additionalProperties": false, "properties": { "journal_entry_public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "posting_date": { "type": "string", "format": "date" }, "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "position_public_id": { "$ref": "#/components/schemas/Ulid" }, "captured_revision": { "type": "integer", "minimum": 1 }, "input": { "$ref": "#/components/schemas/CurrentAccountInterestSavedInput" }, "calculation": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountInterestCalculationSummary" }, { "type": "null" } ] }, "matches_journal_revision": { "type": "boolean", "description": "False after an ordinary journal edit. Saved calculator evidence remains identified with its captured revision." } }, "required": [ "journal_entry_public_id", "revision", "posting_date", "description", "position_public_id", "captured_revision", "input", "calculation", "matches_journal_revision" ] }, "CurrentAccountInterestResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CurrentAccountInterest" } }, "required": [ "data" ] }, "CurrentAccountInterestCollection": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/CurrentAccountInterest" } }, "links": { "type": "object", "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ] } }, "required": [ "next" ] } }, "required": [ "data", "links" ] }, "MollieSettingsInput": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "enabled" ], "oneOf": [ { "required": [ "bank_account_public_id" ], "not": { "required": [ "new_bank_account" ] } }, { "required": [ "new_bank_account" ], "not": { "required": [ "bank_account_public_id" ] } } ], "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "enabled": { "type": "boolean" }, "api_key": { "type": [ "string", "null" ], "writeOnly": true, "maxLength": 105, "description": "Own test_ or live_ profile API key; omission or empty retains the existing key. Never returned or flashed." }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "new_bank_account": { "type": "object", "additionalProperties": false, "description": "Creates an active ordinary account with identifier Mollie and an ordinary bank ledger. Requires banking:write and ledger_accounts:write. No financial entry is posted.", "required": [ "name", "currency_code", "ledger_code", "starts_on" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "A currency supported by the application's versioned currency catalog." }, "ledger_code": { "type": "string", "maxLength": 10, "pattern": "^[A-Za-z0-9]+$" }, "starts_on": { "type": "string", "format": "date" } } } } }, "MollieSettingsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision", "enabled" ], "properties": { "revision": { "type": "integer" }, "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "has_api_key": { "type": "boolean" } } } } }, "MolliePayment": { "type": "object", "additionalProperties": false, "required": [ "public_id", "payment_id", "mode", "document_public_id", "amount", "currency_code", "status", "method", "paid_at", "receipt_public_id", "receipt_deleted", "processing_error" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "payment_id": { "type": "string", "pattern": "^tr_[a-zA-Z0-9]{1,60}$" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Exact amount, four storage decimals" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "status": { "type": "string", "enum": [ "open", "pending", "authorized", "paid", "canceled", "expired", "failed" ] }, "method": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "receipt_public_id": { "type": [ "string", "null" ], "description": "Ordinary receipt public ULID when posted; retained after deletion" }, "receipt_deleted": { "type": "boolean" }, "processing_error": { "type": [ "string", "null" ] } } }, "MolliePaymentResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MolliePayment" } } }, "MolliePaymentsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MolliePayment" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } } } } }, "VatReturnPaymentInput": { "type": "object", "additionalProperties": false, "required": [ "occurred_on", "direction", "amount" ], "properties": { "filing_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "occurred_on": { "type": "string", "format": "date" }, "direction": { "type": "string", "enum": [ "DBIT", "CRDT" ] }, "amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,2})?$", "description": "Positive actual EUR amount, maximum two decimal places. Overpayment is preserved." }, "payment_reference": { "type": [ "string", "null" ], "maxLength": 255 }, "note": { "type": [ "string", "null" ], "maxLength": 255 }, "opening_fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payment_channel": { "type": "string", "enum": [ "bank", "rekening_courant", "linked_administration" ], "description": "Explicit UI choice. An omitted channel with an explicit bank retains the existing own-bank API meaning." }, "paying_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/CurrentAccountEdgeAmountInput" } }, "settlement_native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,12})?$", "description": "Required only for a bank currency different from the bank owner base currency. Actual native cash, not an additional EUR equivalent or guessed rate." }, "day_order": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "phase", "placement", "journal_public_id" ], "properties": { "phase": { "type": "string", "enum": [ "cash" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" } }, "additionalProperties": false }, "description": "Create-only explicit placement of the cash phase against an authorized existing journal on the same actual foreign account and date. Resubmit the complete input and obtain a fresh state_hash. A nonempty choice is always validated, including on a day without saved ordering; an unrelated anchor is rejected. Correction and non-cash routes do not accept this field." } }, "oneOf": [ { "required": [ "filing_public_id" ], "not": { "anyOf": [ { "required": [ "opening_fiscal_year_public_id" ] }, { "required": [ "opening_ledger_account_public_id" ] } ] } }, { "required": [ "opening_fiscal_year_public_id", "opening_ledger_account_public_id" ], "not": { "required": [ "filing_public_id" ] } } ], "description": "Exactly one real source: a recorded VAT filing, or the original opening fiscal year and ledger account. The opening choice settles previously declared Dutch VAT without creating a return. Actual EUR amounts and partial/excess payments retain the existing contract. Uses the existing authorized RC chain and exact native cash. A bank-linked payment must first be unlinked before any correction or removal. Routed writes require VAT and current-account write abilities on every actual owner. All source and valuation consequences are confirmed atomically.", "allOf": [ { "if": { "properties": { "payment_channel": { "const": "rekening_courant" } }, "required": [ "payment_channel" ] }, "then": { "required": [ "contact_public_id" ], "not": { "anyOf": [ { "required": [ "bank_account_public_id" ] }, { "required": [ "paying_administration_public_id" ] }, { "required": [ "settlement_native_amount" ] } ] } }, "else": { "required": [ "bank_account_public_id" ], "not": { "required": [ "contact_public_id" ] } } }, { "if": { "properties": { "payment_channel": { "const": "linked_administration" } }, "required": [ "payment_channel" ] }, "then": { "required": [ "paying_administration_public_id" ] }, "else": { "not": { "required": [ "paying_administration_public_id" ] } } } ] }, "VatReturnPaymentPreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "payment" ], "properties": { "payment": { "$ref": "#/components/schemas/VatReturnPaymentInput" } } }, "VatReturnPaymentRequest": { "type": "object", "additionalProperties": false, "required": [ "payment", "state_hash" ], "properties": { "payment": { "$ref": "#/components/schemas/VatReturnPaymentInput" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "VatReturnPaymentRemovalRequest": { "type": "object", "additionalProperties": false, "required": [ "state_hash" ], "properties": { "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "VatReturnPaymentResult": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VatReturnPaymentSnapshot" } } }, "VatReturnPaymentActive": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "removed", "journal_public_id", "bank_account_public_id", "balance_account_public_id", "date", "direction", "amount", "payment_reference", "note", "payment_channel", "bank_administration_public_id", "contact_public_id", "route", "edge_amounts", "settlement_native_amount", "owner_journals" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "filing_public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "removed": { "const": false }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" }, "bank_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "balance_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "date": { "type": "string", "format": "date" }, "direction": { "enum": [ "DBIT", "CRDT" ] }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "payment_reference": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "opening_fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payment_channel": { "type": "string", "enum": [ "bank", "rekening_courant", "linked_administration" ], "description": "Explicit UI choice. An omitted channel with an explicit bank retains the existing own-bank API meaning." }, "bank_administration_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "contact_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "route": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountLiveRoute" }, { "type": "null" } ] }, "edge_amounts": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAccountEdgeAmount" } }, { "type": "null" } ] }, "settlement_native_amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+\\.\\d{12}$" }, { "type": "null" } ] }, "owner_journals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "administration_public_id", "journal_public_id", "number", "deleted" ], "properties": { "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "integer" }, "deleted": { "type": "boolean" } } } } }, "oneOf": [ { "required": [ "filing_public_id" ], "not": { "anyOf": [ { "required": [ "opening_fiscal_year_public_id" ] }, { "required": [ "opening_ledger_account_public_id" ] } ] } }, { "required": [ "opening_fiscal_year_public_id", "opening_ledger_account_public_id" ], "not": { "required": [ "filing_public_id" ] } } ] }, "VatReturnPaymentRemoved": { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "removed", "journal_public_id" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "filing_public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "removed": { "const": true }, "journal_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" } }, "oneOf": [ { "required": [ "filing_public_id" ], "not": { "anyOf": [ { "required": [ "opening_fiscal_year_public_id" ] }, { "required": [ "opening_ledger_account_public_id" ] } ] } }, { "required": [ "opening_fiscal_year_public_id", "opening_ledger_account_public_id" ], "not": { "required": [ "filing_public_id" ] } } ] }, "VatReturnPaymentSnapshot": { "oneOf": [ { "$ref": "#/components/schemas/VatReturnPaymentActive" }, { "$ref": "#/components/schemas/VatReturnPaymentRemoved" } ] }, "VatReturnPaymentPreview": { "type": "object", "additionalProperties": false, "required": [ "period", "kind", "bank", "balance", "paid", "remaining_before", "remaining_after", "amount", "direction", "date", "currency", "balance_account", "journal_lines", "state_hash", "removal", "old_position" ], "properties": { "filing_public_id": { "$ref": "#/components/schemas/Ulid" }, "period": { "type": "string" }, "kind": { "type": "string" }, "bank": { "type": [ "string", "null" ] }, "balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "paid": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "remaining_before": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "remaining_after": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "direction": { "enum": [ "DBIT", "CRDT" ] }, "date": { "type": "string", "format": "date" }, "currency": { "const": "EUR" }, "balance_account": { "type": "string" }, "journal_lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "ledger_account_id", "side", "storage_amount", "account" ], "properties": { "ledger_account_id": { "type": "integer" }, "side": { "enum": [ "debit", "credit" ] }, "storage_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "account": { "type": "string" } } } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "removal": { "const": false }, "old_position": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "period", "remaining_before", "remaining_after", "kind" ], "properties": { "filing_public_id": { "$ref": "#/components/schemas/Ulid" }, "period": { "type": "string" }, "remaining_before": { "type": "string" }, "remaining_after": { "type": "string" }, "kind": { "type": "string" }, "opening_fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" } }, "oneOf": [ { "required": [ "filing_public_id" ], "not": { "anyOf": [ { "required": [ "opening_fiscal_year_public_id" ] }, { "required": [ "opening_ledger_account_public_id" ] } ] } }, { "required": [ "opening_fiscal_year_public_id", "opening_ledger_account_public_id" ], "not": { "required": [ "filing_public_id" ] } } ] } ] }, "opening_fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_kind": { "type": "string", "enum": [ "filing", "opening" ] }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "removed_journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "payment_channel": { "type": "string", "enum": [ "bank", "rekening_courant", "linked_administration" ], "description": "Explicit UI choice. An omitted channel with an explicit bank retains the existing own-bank API meaning." }, "route": { "oneOf": [ { "$ref": "#/components/schemas/CurrentAccountLiveRoute" }, { "type": "null" } ] }, "settlement_native_amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,12})?$" }, { "type": "null" } ] }, "bank_currency": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "unchanged": { "type": "boolean" } }, "oneOf": [ { "required": [ "filing_public_id" ], "not": { "anyOf": [ { "required": [ "opening_fiscal_year_public_id" ] }, { "required": [ "opening_ledger_account_public_id" ] } ] } }, { "required": [ "opening_fiscal_year_public_id", "opening_ledger_account_public_id" ], "not": { "required": [ "filing_public_id" ] } } ] }, "VatReturnPaymentRemovalPreview": { "type": "object", "additionalProperties": false, "required": [ "state_hash", "removal", "payment", "remaining_before", "remaining_after", "bank" ], "properties": { "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "removal": { "const": true }, "payment": { "$ref": "#/components/schemas/VatReturnPaymentActive" }, "remaining_before": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "remaining_after": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "bank": { "type": [ "string", "null" ] }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "removed_journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } } } }, "VatReturnPaymentPreviewResult": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VatReturnPaymentPreview" } } }, "VatReturnPaymentRemovalPreviewResult": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VatReturnPaymentRemovalPreview" } } }, "VatReturnObligation": { "type": "object", "additionalProperties": false, "required": [ "filing_public_id", "current_filing_public_id", "kind", "period_start", "period_end", "balance", "net_paid", "remaining", "currency_code", "source_check", "removed_registration", "sequence" ], "properties": { "filing_public_id": { "$ref": "#/components/schemas/Ulid" }, "current_filing_public_id": { "$ref": "#/components/schemas/Ulid" }, "kind": { "enum": [ "regular", "supplementation" ] }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "balance": { "type": [ "string", "null" ] }, "net_paid": { "type": [ "string", "null" ] }, "remaining": { "type": [ "string", "null" ] }, "currency_code": { "type": "string" }, "source_check": { "type": [ "string", "null" ] }, "removed_registration": { "type": "boolean" }, "sequence": { "type": "integer", "minimum": 1 } } }, "VatReturnObligationsResult": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VatReturnObligation" } }, "opening_positions": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningVatPosition" } } } }, "FxRevaluationOrderRequired": { "type": "object", "required": [ "message", "errors", "day_order_options" ], "additionalProperties": false, "properties": { "message": { "type": "string" }, "errors": { "type": "object", "required": [ "day_order" ], "properties": { "day_order": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "day_order_options": { "type": "object", "required": [ "revaluation" ], "properties": { "revaluation": { "type": "array", "items": { "type": "object", "required": [ "journal_public_id", "label" ], "properties": { "journal_public_id": { "$ref": "#/components/schemas/Ulid" }, "label": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "description": "Top-level HTTP 422 preview response when another year-control phase on the same account/day needs an explicit relative placement. Resubmit full input with day_order; no financial mutation has occurred." }, "CurrencyExchangePosition": { "type": "object", "additionalProperties": false, "required": [ "ledger_account_public_id", "date", "previous", "next" ], "properties": { "ledger_account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "date": { "type": "string", "format": "date" }, "previous": { "type": [ "string", "null" ], "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "next": { "type": [ "string", "null" ], "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "description": "Exact gap between adjacent retained stored journals on this account and date, after removing old phases of the target source. Null previous/next means start/end; both null is allowed only on an empty retained day. No new phase may serve as a gap boundary. Stale/non-adjacent/cross-account bounds are rejected with refreshed choices." }, "CurrencyExchangePhaseOrder": { "type": "object", "additionalProperties": false, "required": [ "phase", "placement", "anchor_phase" ], "properties": { "phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] }, "placement": { "type": "string", "enum": [ "before", "after" ] }, "anchor_phase": { "type": "string", "enum": [ "trade", "sold", "bought", "fees", "settlement" ] } }, "description": "Explicit relative order of two new phases sharing an account-day. A phase cannot anchor itself; the combined graph must remain acyclic." }, "NativeSignedBalance": { "type": "object", "required": [ "amount", "side" ], "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$" }, "side": { "type": [ "string", "null" ], "enum": [ "debit", "credit", null ] } }, "description": "Exact original-currency balance; up to twelve source decimals. Base-ledger SignedBalance remains limited to four decimals." }, "BrokerInstrument": { "type": "object", "required": [ "public_id", "revision", "name", "external_identifier", "kind", "currency_code", "contract_facts" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 255 }, "external_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "kind": { "type": "string", "enum": [ "share", "option", "fund", "bond", "future", "warrant", "turbo", "crypto", "participation" ] }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "contract_facts": { "oneOf": [ { "type": "object" }, { "type": "null" }, { "type": "array", "maxItems": 0 } ] } }, "description": "Current descriptive identity and existing read-only contract facts. Name/ISIN or symbol corrections preserve this identity and all historical financial input; no separate metadata history is created." }, "BrokerInstrumentUpdate": { "type": "object", "required": [ "name", "external_identifier", "expected_revision" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "external_identifier": { "type": [ "string", "null" ], "maxLength": 255 }, "expected_revision": { "type": "integer", "minimum": 1 } }, "description": "Correct name and identifier of the same instrument. A stale revision is rejected. Currency, kind and financial contract fields are not mutable through this metadata route. Existing prepared trades become stale after a correction." }, "BrokerInstrumentPage": { "type": "object", "required": [ "data", "current_page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerInstrument" } }, "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "description": "Standard paginated instrument collection, 25 instruments per page." }, "BrokerInstrumentDetail": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "instrument", "positions", "transactions" ], "properties": { "instrument": { "$ref": "#/components/schemas/BrokerInstrument" }, "positions": { "type": "array", "items": { "type": "object" } }, "transactions": { "type": "object", "required": [ "data", "current_page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "public_id", "trade_date", "instrument_kind", "action", "reference" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "trade_date": { "type": "string", "format": "date" }, "instrument_kind": { "type": "string" }, "action": { "type": "string" }, "reference": { "type": [ "string", "null" ] } } } }, "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "underlying": { "type": [ "object", "null" ], "properties": { "public_id": { "type": "string" }, "name": { "type": "string" }, "external_identifier": { "type": [ "string", "null" ] }, "currency_code": { "type": "string" } }, "required": [ "public_id", "name", "external_identifier", "currency_code" ], "additionalProperties": false, "description": "Same-administration linked underlying security, if present; descriptive data only." } } } } }, "BrokerInstrumentUpdateResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BrokerInstrument" } } }, "CurrencyExchangeDependentJournal": { "type": "object", "required": [ "source_type", "role", "public_id", "entry_number", "date", "description", "lines", "rounding", "before", "financial_changed" ], "properties": { "source_type": { "type": "string", "description": "Proven journal source type; generic trade/settlement roles do not imply an FX exchange." }, "administration_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "administration_name": { "type": "string" }, "role": { "type": "string", "description": "Exchange phase or retained dependent source phase." }, "public_id": { "oneOf": [ { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "entry_number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "account", "account_public_id", "side", "amount", "base_currency", "currency", "native", "native_currency" ], "properties": { "account": { "type": "string" }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Stored EUR ledger amount. It can be zero while the proven native amount is nonzero." }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "native": { "oneOf": [ { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." }, { "type": "null" } ] }, "native_currency": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, { "type": "null" } ] } }, "additionalProperties": false } }, "rounding": { "oneOf": [ { "type": "object", "required": [ "amount", "side", "account_public_id" ], "properties": { "amount": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "roundings": { "type": "array", "items": { "type": "object", "required": [ "amount", "side", "account_public_id" ], "properties": { "amount": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "cash_leg": { "type": "string", "enum": [ "sold", "bought", "fees" ], "description": "Present when the preview associates this rounding with an actual bank leg." } }, "additionalProperties": false }, "description": "All separately proven rounding amounts in this journal; a joint settlement may contain more than one. The scalar rounding field remains a compatibility projection of the first item." }, "before": { "$ref": "#/components/schemas/CurrencyExchangeJournal" }, "financial_changed": { "type": "boolean", "description": "Presentation classification only. False never skips financial verification or persistence." } }, "additionalProperties": false, "description": "Public journal projection without private database IDs or proof authority. Native values retain their exact precision; ledger values are EUR cents in storage format. Proven rounding is shown separately on the explicitly selected account, never silently labelled an FX result." }, "PeriodicValuationPosition": { "type": "object", "required": [ "ledger_account", "claim_reference", "currency", "base_currency", "native", "before_base", "target_base", "delta_base" ], "additionalProperties": false, "properties": { "ledger_account": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "claim_reference": { "type": [ "string", "null" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$" }, "before_base": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$" }, "target_base": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$" }, "delta_base": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$" } }, "description": "Signed individual cash or gross claim component, including native-zero EUR residues. Exact native decimals remain visible; no internal account ID is exposed." }, "PeriodicValuationPreview": { "type": "object", "required": [ "positions", "journals", "removed_journals", "no_op", "operation" ], "additionalProperties": false, "properties": { "positions": { "type": "array", "items": { "$ref": "#/components/schemas/PeriodicValuationPosition" } }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "removed_journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "no_op": { "type": "boolean", "description": "No source or journal is changed. The revision remains unchanged and prospective mutation rows are omitted." }, "operation": { "type": "string", "enum": [ "create", "update", "remove" ] } } }, "BankTransferDeletePreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "operation", "expected_revision" ], "properties": { "operation": { "const": "delete" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "description": "Periodic local transfer v2 only. Read-only deletion preview of both original journals and every required existing valuation boundary; no financial writes or idempotency reservation." }, "BankTransferDeleteRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Required for an active periodic v2 source. Obtain from the operation=delete preview. The legacy v1 contract rejects this field." } }, "description": "Periodic v2 confirmation binds the complete current source and valuation preview. Legacy v1 retains revision-only deletion." }, "PurchaseSettlementRemovalPreview": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "state_hash", "expected_revision", "journals", "removed_journals" ], "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasePreviewJournal" } }, "removed_journals": { "type": "array", "items": { "type": "object", "required": [ "public_id", "number", "date" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "integer", "minimum": 1 }, "date": { "type": "string", "format": "date" } } } } } } } }, "PreviewOpeningBalanceRequest": { "type": "object", "required": [ "expected_revision", "lines" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "lines": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/OpeningBalanceLineInput" }, "description": "Empty clears; a non-empty array requires at least two balanced lines." } } }, "OpeningBalancePreviewFx": { "type": "object", "required": [ "foreign_currency", "base_currency", "source_foreign_amount", "converted_base_amount", "rate_numerator", "rate_denominator", "convention", "effective_date", "formula_version" ], "additionalProperties": false, "properties": { "foreign_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "source_foreign_amount": { "type": "string" }, "converted_base_amount": { "type": "string" }, "rate_numerator": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "rate_denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "convention": { "type": "string", "const": "base_per_foreign_unit" }, "effective_date": { "type": "string", "format": "date" }, "formula_version": { "type": "integer", "minimum": 1 } } }, "OpeningBalancePreview": { "type": "object", "additionalProperties": false, "required": [ "state_hash", "operation", "opening_balance", "valuation_journals" ], "properties": { "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "operation": { "type": "string", "enum": [ "create", "update", "clear" ] }, "opening_balance": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "public_id", "revision", "date", "lines" ], "properties": { "public_id": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "date": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "ledger_account", "side", "amount", "fx" ], "properties": { "ledger_account": { "$ref": "#/components/schemas/LedgerIdentity" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string" }, "fx": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalancePreviewFx" }, { "type": "null" } ] } } } } } } ] }, "valuation_journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "asset_effects": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "asset_public_id", "name", "mutations" ], "properties": { "asset_public_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "mutations": { "$ref": "#/components/schemas/FixedAssetPostingMutations" } } } }, "opening_vat_effects": { "type": "array", "description": "Existing VAT opening settlements before and after the proposed opening change.", "items": { "type": "object" } }, "opening_private_effects": { "type": "array", "description": "Unchanged explicit opening-position private transfers and the before/after remaining position. No transfer is automatically edited.", "items": { "type": "object", "additionalProperties": false, "required": [ "bank_ledger_account_public_id", "account", "currency_code", "before", "after", "transfers" ], "properties": { "bank_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "account": { "type": "string" }, "currency_code": { "type": "string" }, "before": { "$ref": "#/components/schemas/BankOpeningPrivateAmounts" }, "after": { "$ref": "#/components/schemas/BankOpeningPrivateAmounts" }, "transfers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "public_id", "posting_date", "amount" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "posting_date": { "type": "string", "format": "date" }, "amount": { "type": "string" } } } } } } } } }, "PreviewDeleteCurrentAccountTransactionRequest": { "type": "object", "required": [ "expected_revision" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } }, "CurrentAccountRemovalPreview": { "type": "object", "additionalProperties": false, "required": [ "public_id", "expected_revision", "state_hash", "removed_journals", "valuation_journals" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "removed_journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } }, "valuation_journals": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyExchangeJournal" } } } }, "BrokerCalculatedReportReconciliation": { "type": "object", "required": [ "basis_hash", "source", "date_from", "date_to", "rows" ], "additionalProperties": false, "properties": { "basis_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "source": { "type": "string", "enum": [ "calculated_broker_reconciliation" ] }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "ledger_account", "signed_amount", "amount", "side" ], "additionalProperties": false, "properties": { "ledger_account": { "type": "object", "required": [ "public_id", "code", "name" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "signed_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "side": { "type": "string", "enum": [ "debit", "credit" ] } } } } } }, "FiscalCalendarConfirmation": { "type": "object", "additionalProperties": false, "required": [ "confirmation_token" ], "properties": { "confirmation_token": { "type": "string", "maxLength": 2000000 } }, "description": "Confirm this encrypted complete calendar proposal on the same operation/year route using the same access token. Send only confirmation_token. Stale proposals must be rebuilt." }, "FiscalCalendarAnnualFacts": { "type": "object", "additionalProperties": false, "properties": { "market_price": { "type": "string", "maxLength": 40, "pattern": "^\\d+(?:[.,]\\d+)?$" }, "trade_fx": { "$ref": "#/components/schemas/FreshSharesFxInput" }, "unit_quote_source_id": { "type": "string", "maxLength": 80 }, "fx_quote_source_id": { "type": "string", "maxLength": 80 }, "fiscal_carrying": { "type": [ "string", "null" ], "maxLength": 40 }, "tax_evidence": { "type": [ "string", "null" ], "maxLength": 2000 }, "day_order": { "type": [ "string", "null" ], "maxLength": 64 } }, "description": "Actual annual-source ULIDs only. Prices and FX facts belong to exactly the proposed closing date. Existing quote identifiers can select between conflicting dated observations. Participation values retain their own fiscal contract." }, "FiscalCalendarValues": { "type": "object", "additionalProperties": false, "properties": { "sources": { "type": "object", "maxProperties": 500, "additionalProperties": { "$ref": "#/components/schemas/FiscalCalendarAnnualFacts" } }, "groups": { "type": "object", "maxProperties": 500, "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "members": { "type": "array", "items": { "type": "object" } }, "quantity_choices": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" } } } } }, "group_updates": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BrokerGroupUpdate" } } } }, "FiscalCalendarRemovalRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "calendar_values": { "$ref": "#/components/schemas/FiscalCalendarValues" } } }, { "$ref": "#/components/schemas/FiscalCalendarConfirmation" } ] }, "FiscalCalendarEffect": { "type": "object", "required": [ "date", "lines" ], "properties": { "public_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "date": { "type": [ "string", "null" ], "format": "date" }, "before_date": { "type": [ "string", "null" ], "format": "date" }, "entry_number": { "type": [ "integer", "null" ] }, "removed": { "type": "boolean" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } } } }, "FiscalCalendarPreviewResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "ready", "requires_confirmation", "years_before", "years_after", "missing", "effects", "group_updates" ], "properties": { "ready": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "confirmation_token": { "type": "string" }, "years_before": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } }, "years_after": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } }, "missing": { "type": [ "object", "array" ], "additionalProperties": { "type": "object", "required": [ "source_public_id", "date", "fields" ], "properties": { "source_public_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string" }, "name": { "type": "string" }, "date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "base_currency": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } } } }, "group_updates": { "type": "array", "items": { "type": "object" } }, "effects": { "type": "object", "required": [ "sources", "months", "groups", "foreign" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalCalendarEffect" } }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalCalendarEffect" } }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalCalendarEffect" } }, "foreign": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalCalendarEffect" } }, "purchase_costs": { "type": "array", "items": { "type": "object", "required": [ "date", "lines" ], "properties": { "public_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "date": { "type": [ "string", "null" ], "format": "date" }, "before_date": { "type": [ "string", "null" ], "format": "date" }, "entry_number": { "type": [ "integer", "null" ] }, "removed": { "type": "boolean" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/FreshSharesJournalLine" } }, "document_public_id": { "type": "string" }, "scheduled": { "type": "boolean" } } } } } } } } }, "description": "Read-only financial proposal. ready=false has no confirmation token and identifies missing closing-date facts. Supply these in calendar_values with the same proposed dates. ready=true has not saved anything and must be confirmed. Ordinary real transaction/control dates and closed-year protection remain in force." }, "SalesCreditOrigin": { "type": "object", "additionalProperties": false, "required": [ "public_id", "number", "totals", "credit_split", "fx", "open_item" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": [ "string", "null" ] }, "totals": { "type": "object", "properties": { "native_net_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "native_gross_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "base_net_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "base_gross_amount": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" } }, "additionalProperties": false }, "credit_split": { "$ref": "#/components/schemas/SalesCreditSplit" }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "rate_numerator": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "rate_denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "required": [ "rate_numerator", "rate_denominator" ] }, "open_item": { "type": [ "object", "null" ], "properties": { "native_before": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "native_after": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "base_before": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" }, "base_after": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,4})?$" } }, "additionalProperties": false }, "source_type": { "const": "opening_trade_item" } } }, "PurchasePrivateFundingInput": { "type": "object", "required": [ "settlement_public_id", "amount" ], "additionalProperties": false, "properties": { "settlement_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" } } }, "HistoricalCreditOriginInput": { "type": "object", "required": [ "source_document_public_id", "source_line_public_id", "credit_line_public_id", "net_amount", "vat_amount", "gross_amount" ], "additionalProperties": false, "properties": { "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "source_document_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "credit_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "net_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "vat_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "gross_amount": { "$ref": "#/components/schemas/PurchaseDecimal" } } }, "HistoricalCreditOrigin": { "type": "object", "required": [ "public_id", "source_document_public_id", "source_line_public_id", "credit_line_public_id", "net_amount", "vat_amount", "gross_amount", "source_document_number", "source_line_number", "credit_document_public_id", "credit_document_number" ], "additionalProperties": false, "properties": { "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "source_document_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "credit_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "net_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "vat_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "gross_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "source_document_number": { "type": "string" }, "source_line_number": { "type": [ "integer", "null" ] }, "credit_document_public_id": { "$ref": "#/components/schemas/Ulid" }, "credit_document_number": { "type": "string" } } }, "HistoricalCreditOriginChange": { "type": "object", "required": [ "public_id", "action" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "action": { "type": "string", "enum": [ "keep", "remove", "replace" ] }, "net_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "vat_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "gross_amount": { "$ref": "#/components/schemas/PurchaseDecimal" } } }, "HistoricalCreditOriginsInput": { "type": "object", "required": [ "expected_revision", "allocations" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOriginInput" }, "maxItems": 100 } } }, "HistoricalCreditOriginsCommand": { "type": "object", "required": [ "expected_revision", "allocations", "state_hash" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOriginInput" }, "maxItems": 100 }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" } } }, "HistoricalCreditUnassigned": { "type": "object", "required": [ "native_net_amount", "native_vat_amount", "native_gross_amount", "base_net_amount", "base_vat_amount", "base_gross_amount" ], "additionalProperties": false, "properties": { "native_net_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "native_vat_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "native_gross_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "base_net_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "base_vat_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "base_gross_amount": { "$ref": "#/components/schemas/PurchaseDecimal" } } }, "HistoricalCreditOriginsPreview": { "type": "object", "required": [ "state_hash", "before", "after", "unassigned", "source_capacity" ], "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "before": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOrigin" } }, "after": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOrigin" } }, "unassigned": { "$ref": "#/components/schemas/HistoricalCreditUnassigned" }, "source_capacity": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditSourceCapacity" } } } }, "HistoricalCreditOriginsRead": { "type": "object", "required": [ "revision", "origins" ], "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 0 }, "origins": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOrigin" } } } }, "HistoricalCreditOriginsResult": { "type": "object", "required": [ "public_id", "revision", "origins", "unassigned", "journal_entries" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 0 }, "origins": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalCreditOrigin" } }, "unassigned": { "$ref": "#/components/schemas/HistoricalCreditUnassigned" }, "journal_entries": { "type": "array", "items": { "type": "object", "required": [ "public_id" ], "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" } } } } } }, "HistoricalCreditOriginsReadResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/HistoricalCreditOriginsRead" } } }, "HistoricalCreditOriginsPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/HistoricalCreditOriginsPreview" } } }, "HistoricalCreditOriginsResultResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/HistoricalCreditOriginsResult" } } }, "HistoricalCreditSourceCapacity": { "type": "object", "required": [ "source_document_public_id", "source_line_public_id", "source_document_number", "source_line_number", "stored", "used_elsewhere", "proposed", "available", "remaining" ], "additionalProperties": false, "properties": { "source_document_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_line_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_document_number": { "type": "string" }, "source_line_number": { "type": "integer" }, "stored": { "$ref": "#/components/schemas/HistoricalCreditUnassigned" }, "used_elsewhere": { "$ref": "#/components/schemas/HistoricalCreditUnassigned" }, "proposed": { "$ref": "#/components/schemas/HistoricalCreditUnassigned" }, "available": { "$ref": "#/components/schemas/HistoricalCreditUnassigned" }, "remaining": { "$ref": "#/components/schemas/HistoricalCreditUnassigned" } } }, "PurchasePrivateFundingEvidence": { "type": "object", "required": [ "settlement_public_id", "native_currency_code", "base_currency_code", "claim_currency_code", "native_funding_amount", "historical_base_amount", "claim_amount", "funding_basis" ], "additionalProperties": false, "properties": { "settlement_public_id": { "$ref": "#/components/schemas/Ulid" }, "native_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "base_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "claim_currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_funding_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "historical_base_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "claim_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "funding_basis": { "type": "string", "enum": [ "document", "supplier_credit" ] } } }, "PurchasePayrollFields": { "type": "object", "additionalProperties": false, "required": [ "document_type", "document_date", "payroll" ], "properties": { "document_type": { "enum": [ "salary", "payroll_tax_return" ] }, "document_date": { "type": "string", "format": "date" }, "supplier_public_id": { "$ref": "#/components/schemas/Ulid" }, "external_number": { "type": [ "string", "null" ], "maxLength": 80 }, "payroll": { "type": "object", "additionalProperties": false, "required": [ "cost_account_public_id" ], "properties": { "cost_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "net_amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Nonnegative amount in administration currency, using that currency minor-unit precision." }, "tax_amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Nonnegative amount in administration currency, using that currency minor-unit precision." }, "holiday_accrual": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Nonnegative amount in administration currency, using that currency minor-unit precision." }, "holiday_release": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Nonnegative amount in administration currency, using that currency minor-unit precision." } } }, "payment": { "$ref": "#/components/schemas/PurchaseEmbeddedPaymentInput" }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "allOf": [ { "if": { "properties": { "document_type": { "const": "salary" } } }, "then": { "required": [ "supplier_public_id" ], "properties": { "payroll": { "required": [ "net_amount" ], "not": { "required": [ "tax_amount" ] } } } }, "else": { "not": { "required": [ "supplier_public_id" ] }, "properties": { "payroll": { "required": [ "tax_amount" ], "not": { "anyOf": [ { "required": [ "net_amount" ] }, { "required": [ "holiday_accrual" ] }, { "required": [ "holiday_release" ] } ] } } } } } ] }, "PurchasePayrollData": { "type": "object", "additionalProperties": false, "required": [ "net_amount", "tax_amount", "holiday_accrual", "holiday_release", "cost_account", "liability_account", "holiday_account" ], "properties": { "net_amount": { "type": "string" }, "tax_amount": { "type": "string" }, "holiday_accrual": { "type": "string" }, "holiday_release": { "type": "string" }, "cost_account": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "liability_account": { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "holiday_account": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "public_id", "code", "name" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, { "type": "null" } ] } } }, "SalesBadDebtRecoveryPreview": { "oneOf": [ { "type": "array", "maxItems": 0 }, { "type": "object", "additionalProperties": false, "required": [ "contract", "write_off_public_id", "document_public_id", "date", "receivable", "loss", "loss_account_public_id", "lines", "vat" ], "properties": { "contract": { "const": "sales-bad-debt-recovery-v1" }, "write_off_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "date": { "type": "string", "format": "date" }, "receivable": { "type": "string" }, "loss": { "type": "string" }, "loss_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "ledger_account_public_id", "side", "amount", "component" ], "properties": { "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "side": { "enum": [ "debit", "credit" ] }, "amount": { "type": "string" }, "component": { "enum": [ "debt_receivable", "debt_recovery", "debt_vat_deferred", "debt_vat_due" ] } } } }, "vat": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "line_public_id", "line_number", "system", "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount", "ledger_effects", "reporting_effects" ], "properties": { "line_public_id": { "type": "string" }, "line_number": { "type": "integer" }, "system": { "enum": [ "cash", "invoice" ] }, "native_taxable_amount": { "type": "string" }, "native_vat_amount": { "type": "string" }, "base_taxable_amount": { "type": "string" }, "base_vat_amount": { "type": "string" }, "ledger_effects": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPublicLedgerEffect" } }, "reporting_effects": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "scheme", "code", "component", "route_condition", "amount", "base_amount" ], "properties": { "scheme": { "type": "string" }, "code": { "type": "string" }, "component": { "type": "string" }, "route_condition": { "type": "string" }, "amount": { "type": "string" }, "base_amount": { "type": "string" } } } } } } } } } ] }, "PurchasePayableAllocationInput": { "type": "object", "required": [ "amount" ], "additionalProperties": false, "properties": { "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "opening_item_public_id": { "$ref": "#/components/schemas/Ulid" } }, "oneOf": [ { "required": [ "document_public_id" ], "not": { "required": [ "opening_item_public_id" ] } }, { "required": [ "opening_item_public_id" ], "not": { "required": [ "document_public_id" ] } } ] }, "OpeningTradeVatPartInput": { "type": "object", "additionalProperties": false, "properties": { "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "vat_treatment_version_id": { "type": "integer", "minimum": 1 }, "reporting_route": { "oneOf": [ { "type": "string", "enum": [ "ordinary_nl", "oss", "foreign_return" ] }, { "type": "null" } ] } }, "required": [ "vat_treatment_version_id", "native_taxable_amount", "native_vat_amount" ], "description": "Opening-item historical VAT evidence excludes individual_margin and global_margin_deferred: the margin taxable profit and sale proceeds require separate source facts, and global margin requires its own pool. Unsupported strategies return 422 without a fiscal fallback. Recognized opening items can still be recorded and settled without recognizing VAT again. Explicit destination/OSS/foreign-return evidence remains supported." }, "OpeningTradeItemInput": { "type": "object", "additionalProperties": false, "properties": { "opening_balance_public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_opening_revision": { "type": "integer", "minimum": 1 }, "expected_revision": { "type": "integer", "minimum": 0 }, "subledger_kind": { "type": "string", "enum": [ "sales", "purchase" ] }, "direction": { "type": "string", "enum": [ "receivable", "payable" ] }, "contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_carrying_amount": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, { "type": "null" } ], "description": "Actual carried-over book value. In administration currency it may differ from the claim only with proved historical Receivables reduction; gross settlement carrying remains separate." }, "vat_status": { "type": "string", "enum": [ "recognized", "cash" ] }, "reference": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "original_document_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "due_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "vat_parts": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/OpeningTradeVatPartInput" } }, "historical_vat_boundary": { "$ref": "#/components/schemas/OpeningHistoricalVatBoundaryInput" } }, "required": [ "opening_balance_public_id", "expected_opening_revision", "expected_revision", "subledger_kind", "direction", "contact_public_id", "currency_code", "native_amount", "vat_status" ] }, "ConfirmOpeningTradeItemInput": { "type": "object", "additionalProperties": false, "properties": { "opening_balance_public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_opening_revision": { "type": "integer", "minimum": 1 }, "expected_revision": { "type": "integer", "minimum": 0 }, "subledger_kind": { "type": "string", "enum": [ "sales", "purchase" ] }, "direction": { "type": "string", "enum": [ "receivable", "payable" ] }, "contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_carrying_amount": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, { "type": "null" } ] }, "vat_status": { "type": "string", "enum": [ "recognized", "cash" ] }, "reference": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "original_document_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "due_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "vat_parts": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/OpeningTradeVatPartInput" } }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" } }, "required": [ "opening_balance_public_id", "expected_opening_revision", "expected_revision", "subledger_kind", "direction", "contact_public_id", "currency_code", "native_amount", "vat_status", "state_hash" ] }, "OpeningTradeItemRemovalInput": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "expected_revision" ] }, "ConfirmOpeningTradeItemRemovalInput": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" } }, "required": [ "expected_revision", "state_hash" ] }, "OpeningTradeReportingFact": { "type": "object", "additionalProperties": false, "properties": { "scheme": { "type": "string" }, "code": { "type": "string" }, "component": { "type": "string" }, "route_condition": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" } }, "required": [ "scheme", "code", "component", "route_condition", "amount", "base_amount" ] }, "OpeningTradeVatPart": { "type": "object", "additionalProperties": false, "properties": { "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_version_id": { "type": "integer", "minimum": 1 }, "reporting_route": { "oneOf": [ { "type": "string", "enum": [ "ordinary_nl", "oss", "foreign_return" ] }, { "type": "null" } ] }, "part_number": { "type": "integer", "minimum": 1 }, "deferred_ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "due_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "reporting_facts": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningTradeReportingFact" } }, "bad_debt_history": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBadDebtHistory" }, { "type": "null" } ] } }, "required": [ "public_id", "part_number", "vat_treatment_version_id", "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount", "deferred_ledger_account_public_id", "due_ledger_account_public_id", "reporting_facts", "reporting_route" ] }, "OpeningTradeItem": { "type": "object", "additionalProperties": false, "properties": { "opening_balance_public_id": { "$ref": "#/components/schemas/Ulid" }, "subledger_kind": { "type": "string", "enum": [ "sales", "purchase" ] }, "direction": { "type": "string", "enum": [ "receivable", "payable" ] }, "contact_public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_carrying_amount": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, { "type": "null" } ] }, "vat_status": { "type": "string", "enum": [ "recognized", "cash" ] }, "reference": { "oneOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "original_document_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "due_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "vat_parts": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningTradeVatPart" } }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "control_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "historical_vat_boundary": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "contract": { "const": "opening-cash-vat-boundary-v1" }, "received": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "recognized": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" } }, "required": [ "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount" ], "patternProperties": { "^effect:(native|base):\\d+$": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" } } } } }, "required": [ "contract", "received", "recognized" ] }, { "type": "object", "additionalProperties": false, "properties": { "contract": { "const": "opening-recognized-vat-boundary-v1" }, "received": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "tax_point_system": { "type": "string", "enum": [ "invoice", "cash" ] } }, "required": [ "contract", "received", "tax_point_system" ] }, { "type": "null" } ] }, "opening_date": { "type": "string", "format": "date" }, "contact": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" } }, "required": [ "public_id", "name" ] }, "control_account": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "public_id", "code", "name" ] }, "position": { "type": "object", "additionalProperties": false, "properties": { "native_outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_carrying_outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "base_book_outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "written_off": { "type": "boolean" } }, "required": [ "native_outstanding", "base_carrying_outstanding", "base_book_outstanding", "written_off" ] } }, "required": [ "opening_balance_public_id", "subledger_kind", "direction", "contact_public_id", "currency_code", "native_amount", "base_carrying_amount", "vat_status", "reference", "original_document_date", "due_date", "vat_parts", "public_id", "administration_public_id", "control_ledger_account_public_id", "revision", "historical_vat_boundary" ] }, "OpeningTradeItemDeleted": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "deleted": { "const": true } }, "required": [ "public_id", "administration_public_id", "deleted" ] }, "OpeningTradeItemResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/OpeningTradeItem" }, { "$ref": "#/components/schemas/OpeningTradeItemDeleted" } ] } }, "required": [ "data" ] }, "OpeningTradeItemCollection": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningTradeItem" } }, "meta": { "type": "object", "additionalProperties": false, "properties": { "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "previous_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "next_cursor", "previous_cursor" ] } }, "required": [ "data", "meta" ] }, "OpeningTradeSpecification": { "type": "object", "additionalProperties": false, "properties": { "opening_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "specified_opening_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "unspecified_opening_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "specified_receivable": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "specified_payable": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "specified_current_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{4}$" }, "item_count": { "type": "integer", "minimum": 0 }, "amounts_distributed": { "type": "boolean" }, "subledger_kind": { "type": "string", "enum": [ "sales", "purchase" ] } }, "required": [ "opening_balance", "specified_opening_balance", "unspecified_opening_balance", "specified_receivable", "specified_payable", "item_count", "amounts_distributed" ] }, "OpeningTradeVatPartPreview": { "type": "object", "additionalProperties": false, "properties": { "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_version_id": { "type": "integer", "minimum": 1 }, "reporting_route": { "oneOf": [ { "type": "string", "enum": [ "ordinary_nl", "oss", "foreign_return" ] }, { "type": "null" } ] }, "part_number": { "type": "integer", "minimum": 1 }, "reporting_facts": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningTradeReportingFact" } }, "treatment_code": { "type": "string" }, "treatment_version": { "type": "integer", "minimum": 1 }, "bad_debt_history": { "oneOf": [ { "$ref": "#/components/schemas/OpeningBadDebtHistory" }, { "type": "null" } ] } }, "required": [ "public_id", "part_number", "vat_treatment_version_id", "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount", "treatment_code", "treatment_version", "reporting_facts" ] }, "OpeningTradeItemPreview": { "type": "object", "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "source_type": { "const": "opening_trade_item" }, "public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "opening_date": { "type": "string", "format": "date" }, "subledger_kind": { "type": "string", "enum": [ "sales", "purchase" ] }, "direction": { "type": "string", "enum": [ "receivable", "payable" ] }, "contact": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" } }, "required": [ "public_id", "name" ] }, "control_account": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "public_id", "code", "name" ] }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_carrying_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "vat_status": { "type": "string", "enum": [ "recognized", "cash" ] }, "vat_parts": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningTradeVatPartPreview" } }, "opening_reconciliation": { "$ref": "#/components/schemas/OpeningTradeSpecification" }, "opening_reconciliation_after": { "$ref": "#/components/schemas/OpeningTradeSpecification" }, "journal_entries": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SalesPreviewJournalEntry" }, { "$ref": "#/components/schemas/PurchasePreviewJournal" } ] } }, "historical_vat_boundary": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "contract": { "const": "opening-cash-vat-boundary-v1" }, "received": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "recognized": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" } }, "required": [ "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount" ], "patternProperties": { "^effect:(native|base):\\d+$": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" } } } } }, "required": [ "contract", "received", "recognized" ] }, { "type": "object", "additionalProperties": false, "properties": { "contract": { "const": "opening-recognized-vat-boundary-v1" }, "received": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "tax_point_system": { "type": "string", "enum": [ "invoice", "cash" ] } }, "required": [ "contract", "received", "tax_point_system" ] }, { "type": "null" } ] } }, "required": [ "state_hash", "source_type", "public_id", "opening_date", "subledger_kind", "direction", "contact", "control_account", "currency_code", "native_amount", "base_carrying_amount", "vat_status", "vat_parts", "opening_reconciliation", "opening_reconciliation_after", "journal_entries", "historical_vat_boundary" ] }, "OpeningTradeItemPreviewResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OpeningTradeItemPreview" } }, "required": [ "data" ] }, "OpeningTradeItemRemovalPreviewResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "state_hash": { "$ref": "#/components/schemas/PurchaseStateHash" }, "source": { "$ref": "#/components/schemas/OpeningTradeItem" }, "journal_entries": { "type": "array", "maxItems": 0 }, "deleted": { "const": true } }, "required": [ "state_hash", "source", "journal_entries", "deleted" ] } }, "required": [ "data" ] }, "ContactOpeningItem": { "type": "object", "additionalProperties": false, "required": [ "public_id", "subledger_kind", "direction", "reference", "opening_date", "currency_code", "native_amount", "native_outstanding" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "subledger_kind": { "type": "string", "enum": [ "sales", "purchase" ] }, "direction": { "type": "string", "enum": [ "receivable", "payable" ] }, "reference": { "type": [ "string", "null" ] }, "opening_date": { "type": "string", "format": "date" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "native_amount": { "type": "string" }, "native_outstanding": { "type": "string" } } }, "OpeningHistoricalVatBoundaryInput": { "type": "object", "additionalProperties": false, "properties": { "received": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "parts": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" } }, "required": [ "public_id", "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount" ] }, { "type": "object", "additionalProperties": false, "properties": { "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_version_id": { "type": "integer", "minimum": 1 }, "reporting_route": { "oneOf": [ { "type": "string", "enum": [ "ordinary_nl", "oss", "foreign_return" ] }, { "type": "null" } ] }, "bad_debt_history": { "$ref": "#/components/schemas/OpeningBadDebtHistory" } }, "required": [ "vat_treatment_version_id", "native_taxable_amount", "native_vat_amount" ] } ] } }, "tax_point_system": { "type": "string", "enum": [ "invoice", "cash" ] } }, "required": [ "received", "parts" ], "allOf": [ { "if": { "required": [ "tax_point_system" ] }, "then": { "properties": { "parts": { "items": { "type": "object", "additionalProperties": false, "properties": { "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "vat_treatment_version_id": { "type": "integer", "minimum": 1 }, "reporting_route": { "oneOf": [ { "type": "string", "enum": [ "ordinary_nl", "oss", "foreign_return" ] }, { "type": "null" } ] }, "bad_debt_history": { "$ref": "#/components/schemas/OpeningBadDebtHistory" } }, "required": [ "vat_treatment_version_id", "native_taxable_amount", "native_vat_amount" ] } } } }, "else": { "properties": { "parts": { "items": { "type": "object", "additionalProperties": false, "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "native_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "native_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_taxable_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "base_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" } }, "required": [ "public_id", "native_taxable_amount", "native_vat_amount", "base_taxable_amount", "base_vat_amount" ] } } } } } ], "description": "Opening-item historical VAT evidence excludes individual_margin and global_margin_deferred: the margin taxable profit and sale proceeds require separate source facts, and global margin requires its own pool. Unsupported strategies return 422 without a fiscal fallback. Recognized opening items can still be recorded and settled without recognizing VAT again. Explicit destination/OSS/foreign-return evidence remains supported." }, "SalesOpeningFiscalContext": { "type": "object", "additionalProperties": false, "properties": { "tax_point_system": { "type": "string", "enum": [ "invoice", "cash" ] }, "evidence_kind": { "const": "opening_fiscal_part" }, "opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_vat_part_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_revision": { "type": "integer", "minimum": 1 } }, "required": [ "tax_point_system", "evidence_kind", "opening_item_public_id", "opening_vat_part_public_id", "source_revision" ] }, "OpeningBadDebtHistory": { "type": "object", "additionalProperties": false, "required": [ "remaining_vat_amount", "prior_relief_amount", "receivable_reduction_amount" ], "properties": { "remaining_vat_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "prior_relief_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "receivable_reduction_amount": { "type": "string", "pattern": "^\\d{1,15}(?:\\.\\d{1,4})?$" }, "recovery_ledger_account_public_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Required only for relief recorded outside Receivables; the original account is retained." } } }, "OpeningBadDebtInput": { "type": "object", "additionalProperties": false, "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "remove": { "type": "boolean" }, "written_off_on": { "type": "string", "format": "date" }, "vat_date": { "type": [ "string", "null" ], "format": "date" }, "loss_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" } }, "allOf": [ { "if": { "properties": { "remove": { "const": true } }, "required": [ "remove" ] }, "else": { "required": [ "written_off_on", "loss_ledger_account_public_id" ] } } ] }, "PostOpeningBadDebtRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "state_hash" ], "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "remove": { "type": "boolean" }, "written_off_on": { "type": "string", "format": "date" }, "vat_date": { "type": [ "string", "null" ], "format": "date" }, "loss_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "allOf": [ { "if": { "properties": { "remove": { "const": true } }, "required": [ "remove" ] }, "else": { "required": [ "written_off_on", "loss_ledger_account_public_id" ] } } ] }, "OpeningBadDebtPreview": { "type": "object", "additionalProperties": false, "required": [ "state_hash", "public_id", "expected_revision", "journal_entries", "removed_journals", "vat_facts", "removing" ], "properties": { "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer" }, "journal_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SalesPreviewJournalEntry" } }, "removed_journals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "number", "date", "administration_name" ], "properties": { "number": { "type": "string" }, "date": { "type": "string", "format": "date" }, "administration_name": { "type": "string" } } } }, "vat_facts": { "type": "array", "items": { "type": "object" } }, "removing": { "type": "boolean" } } }, "OpeningBadDebtResult": { "type": "object", "additionalProperties": false, "required": [ "public_id", "opening_item_public_id", "revision", "deleted", "journal" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_item_public_id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "deleted": { "type": "boolean" }, "journal": { "type": "object", "additionalProperties": false, "required": [ "public_id", "number" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "number": { "type": "string" } } } } }, "OpeningBadDebtPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OpeningBadDebtPreview" } } }, "OpeningBadDebtResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OpeningBadDebtResult" } } }, "BankOwnerMovementInput": { "type": "object", "additionalProperties": false, "required": [ "kind", "posting_date", "bank_account_public_id", "private_ledger_account_public_id", "amount" ], "properties": { "kind": { "type": "string", "enum": [ "withdrawal", "contribution" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No private bank account is registered." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." } } }, "BankOwnerMovementUpdate": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "withdrawal", "contribution" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No private bank account is registered." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "posting_date", "bank_account_public_id", "private_ledger_account_public_id", "amount", "expected_revision", "state_hash" ] }, "BankOwnerMovementRemove": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "expected_revision", "state_hash" ] }, "BankOwnerMovementPreviewRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "withdrawal", "contribution" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No private bank account is registered." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "expected_revision": { "type": "integer", "minimum": 1 }, "operation": { "const": "update" } }, "required": [ "kind", "posting_date", "bank_account_public_id", "private_ledger_account_public_id", "amount", "expected_revision", "operation" ] }, { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "operation": { "const": "remove" } }, "required": [ "expected_revision", "operation" ] } ] }, "OpeningVatPosition": { "type": "object", "additionalProperties": false, "required": [ "opening_fiscal_year_public_id", "opening_ledger_account_public_id", "source_kind", "balance", "net_paid", "remaining", "currency_code" ], "properties": { "opening_fiscal_year_public_id": { "$ref": "#/components/schemas/Ulid" }, "opening_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "source_kind": { "const": "opening" }, "balance": { "type": "string" }, "net_paid": { "type": "string" }, "remaining": { "type": "string" }, "currency_code": { "const": "EUR" } } }, "BankTaxMovementInput": { "type": "object", "additionalProperties": false, "required": [ "kind", "posting_date", "bank_account_public_id", "tax_ledger_account_public_id", "amount" ], "properties": { "kind": { "type": "string", "enum": [ "payment", "refund" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional reference. Does not infer a tax year or assessment." } } }, "BankTaxMovementUpdate": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "payment", "refund" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional reference. Does not infer a tax year or assessment." } }, "required": [ "kind", "posting_date", "bank_account_public_id", "tax_ledger_account_public_id", "amount", "expected_revision", "state_hash" ] }, "BankTaxMovementRemove": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "expected_revision", "state_hash" ] }, "BankTaxMovementPreviewRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "payment", "refund" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "expected_revision": { "type": "integer", "minimum": 1 }, "operation": { "const": "update" }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional reference. Does not infer a tax year or assessment." } }, "required": [ "kind", "posting_date", "bank_account_public_id", "tax_ledger_account_public_id", "amount", "expected_revision", "operation" ] }, { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "operation": { "const": "remove" } }, "required": [ "expected_revision", "operation" ] } ] }, "BalanceDestinationPreview": { "type": "object", "additionalProperties": false, "required": [ "account_public_id", "account", "date", "currency", "normal_balance", "before_amount", "after_amount" ], "properties": { "account_public_id": { "$ref": "#/components/schemas/Ulid" }, "account": { "type": "string" }, "date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "before_amount": { "type": "string" }, "after_amount": { "type": "string" } } }, "BankOpeningPrivateInput": { "type": "object", "additionalProperties": false, "required": [ "posting_date", "bank_ledger_account_public_id", "private_ledger_account_public_id", "amount", "expected_revision" ], "properties": { "posting_date": { "type": "string", "format": "date" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact amount of the explicitly transferred opening position. No bank transaction or private bank account is created." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "bank_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 0 } } }, "BankOpeningPrivateConfirm": { "type": "object", "additionalProperties": false, "required": [ "posting_date", "bank_ledger_account_public_id", "private_ledger_account_public_id", "amount", "expected_revision", "state_hash" ], "properties": { "posting_date": { "type": "string", "format": "date" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact amount of the explicitly transferred opening position. No bank transaction or private bank account is created." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "bank_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 0 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "BankOpeningPrivatePreviewRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "posting_date", "bank_ledger_account_public_id", "private_ledger_account_public_id", "amount", "expected_revision", "operation" ], "properties": { "posting_date": { "type": "string", "format": "date" }, "private_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact amount of the explicitly transferred opening position. No bank transaction or private bank account is created." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "bank_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 0 }, "operation": { "type": "string", "enum": [ "create", "update" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "operation" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "operation": { "const": "remove" } } } ] }, "BankOpeningPrivateAmounts": { "type": "object", "additionalProperties": false, "required": [ "opening_present", "opening_amount", "transferred_amount", "remaining_amount" ], "properties": { "opening_present": { "type": "boolean" }, "opening_amount": { "type": "string" }, "transferred_amount": { "type": "string" }, "remaining_amount": { "type": "string" } } }, "BankBalanceMovementInput": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "liability_payment", "dividend_payment", "dividend_tax_payment" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional payment reference." }, "dividend_declaration_public_id": { "$ref": "#/components/schemas/Ulid" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" } }, "required": [ "kind", "posting_date", "bank_account_public_id", "amount" ], "allOf": [ { "if": { "properties": { "kind": { "const": "liability_payment" } } }, "then": { "required": [ "balance_ledger_account_public_id" ] }, "else": { "required": [ "dividend_declaration_public_id" ] } } ] }, "BankBalanceMovementUpdate": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "liability_payment", "dividend_payment", "dividend_tax_payment" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional payment reference." }, "dividend_declaration_public_id": { "$ref": "#/components/schemas/Ulid" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "posting_date", "bank_account_public_id", "amount", "state_hash", "expected_revision" ], "allOf": [ { "if": { "properties": { "kind": { "const": "liability_payment" } } }, "then": { "required": [ "balance_ledger_account_public_id" ] }, "else": { "required": [ "dividend_declaration_public_id" ] } } ] }, "BankBalanceMovementRemove": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "expected_revision", "state_hash" ] }, "BankBalanceMovementPreviewRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "liability_payment", "dividend_payment", "dividend_tax_payment" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "balance_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional payment reference." }, "dividend_declaration_public_id": { "$ref": "#/components/schemas/Ulid" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "expected_revision": { "type": "integer", "minimum": 1 }, "operation": { "const": "update" } }, "required": [ "kind", "posting_date", "bank_account_public_id", "amount", "expected_revision", "operation" ], "allOf": [ { "if": { "properties": { "kind": { "const": "liability_payment" } } }, "then": { "required": [ "balance_ledger_account_public_id" ] }, "else": { "required": [ "dividend_declaration_public_id" ] } } ] }, { "type": "object", "additionalProperties": false, "properties": { "operation": { "const": "remove" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "operation", "expected_revision" ] } ] }, "DividendDeclarationInput": { "type": "object", "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "gross_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,4})?$" }, "withholding_amount": { "type": [ "string", "null" ], "description": "Actual withholding; absent/empty is explicitly no withholding, never an inferred legal exemption." }, "reserve_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "dividend_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } }, "required": [ "posting_date", "shareholder_public_id", "gross_amount", "reserve_ledger_account_public_id" ] }, "DividendDeclarationCreate": { "type": "object", "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "gross_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,4})?$" }, "withholding_amount": { "type": [ "string", "null" ], "description": "Actual withholding; absent/empty is explicitly no withholding, never an inferred legal exemption." }, "reserve_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "dividend_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "posting_date", "shareholder_public_id", "gross_amount", "reserve_ledger_account_public_id", "state_hash" ] }, "DividendDeclarationUpdate": { "type": "object", "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "gross_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,4})?$" }, "withholding_amount": { "type": [ "string", "null" ], "description": "Actual withholding; absent/empty is explicitly no withholding, never an inferred legal exemption." }, "reserve_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "dividend_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "posting_date", "shareholder_public_id", "gross_amount", "reserve_ledger_account_public_id", "state_hash", "expected_revision" ] }, "DividendDeclarationRemove": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "expected_revision", "state_hash" ] }, "DividendDeclarationPreviewRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "gross_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,4})?$" }, "withholding_amount": { "type": [ "string", "null" ], "description": "Actual withholding; absent/empty is explicitly no withholding, never an inferred legal exemption." }, "reserve_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "dividend_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "operation": { "const": "create" } }, "required": [ "posting_date", "shareholder_public_id", "gross_amount", "reserve_ledger_account_public_id", "operation" ] }, { "type": "object", "additionalProperties": false, "properties": { "posting_date": { "type": "string", "format": "date" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "gross_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,4})?$" }, "withholding_amount": { "type": [ "string", "null" ], "description": "Actual withholding; absent/empty is explicitly no withholding, never an inferred legal exemption." }, "reserve_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "dividend_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "operation": { "const": "update" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "posting_date", "shareholder_public_id", "gross_amount", "reserve_ledger_account_public_id", "operation", "expected_revision" ] }, { "type": "object", "additionalProperties": false, "properties": { "operation": { "const": "remove" }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "operation", "expected_revision" ] } ] }, "DividendSettingsInput": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 0 }, "dividend_ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "tax_ledger_account_public_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } }, "required": [ "expected_revision", "dividend_ledger_account_public_id" ] }, "BankDividendPaymentInput": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "dividend_payment", "dividend_tax_payment" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional payment reference." }, "dividend_declaration_public_id": { "$ref": "#/components/schemas/Ulid" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "declaration": { "$ref": "#/components/schemas/DividendDeclarationInput" } }, "required": [ "kind", "posting_date", "bank_account_public_id", "amount" ], "oneOf": [ { "required": [ "dividend_declaration_public_id" ] }, { "required": [ "declaration" ] } ] }, "BankDividendPaymentConfirm": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "dividend_payment", "dividend_tax_payment" ] }, "posting_date": { "type": "string", "format": "date" }, "bank_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "amount": { "type": "string", "description": "Positive exact native bank amount, at most 12 decimal places. No new expense or VAT is recorded." }, "fx": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "conversion_mode": { "type": "string", "enum": [ "rate", "converted_amount" ] }, "rate": { "type": "string" }, "converted_base_amount": { "type": "string" } }, "required": [ "conversion_mode" ], "description": "Required only for foreign bank currency. Exactly one matching rate or actual administration-currency equivalent. No inferred exchange rate." }, "reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Optional payment reference." }, "dividend_declaration_public_id": { "$ref": "#/components/schemas/Ulid" }, "shareholder_public_id": { "$ref": "#/components/schemas/Ulid" }, "declaration": { "$ref": "#/components/schemas/DividendDeclarationInput" }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "posting_date", "bank_account_public_id", "amount", "state_hash" ], "oneOf": [ { "required": [ "dividend_declaration_public_id" ] }, { "required": [ "declaration" ] } ] }, "JournalOpeningItemEffect": { "type": "object", "additionalProperties": false, "required": [ "public_id", "label", "before", "reduction", "after", "previous_reduction" ], "properties": { "public_id": { "$ref": "#/components/schemas/Ulid" }, "label": { "type": "string" }, "before": { "type": "string" }, "reduction": { "type": "string" }, "after": { "type": "string" }, "previous_reduction": { "type": "string" } } }, "JournalPeriodicValuation": { "type": "object", "required": [ "source_type", "role", "public_id", "entry_number", "date", "description", "lines", "rounding", "heading", "currency_code" ], "properties": { "before": { "$ref": "#/components/schemas/CurrencyExchangeJournal", "description": "Existing valuation journal before an in-place update; keeps the same journal identity." }, "before_label": { "type": "string" }, "after_label": { "type": "string" }, "source_type": { "type": "string", "description": "Proven journal source type; generic trade/settlement roles do not imply an FX exchange." }, "administration_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "administration_name": { "type": "string" }, "role": { "type": "string", "description": "Exchange phase or retained dependent source phase." }, "public_id": { "oneOf": [ { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "entry_number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "account", "account_public_id", "side", "amount", "base_currency", "currency", "native", "native_currency" ], "properties": { "account": { "type": "string" }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Stored EUR ledger amount. It can be zero while the proven native amount is nonzero." }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, "native": { "oneOf": [ { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,12})?$", "description": "Exact native amount as a decimal string; never inferred from the rounded EUR ledger amount." }, { "type": "null" } ] }, "native_currency": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Supported code from the application currency catalog; the selected Bank account fixes its currency." }, { "type": "null" } ] }, "code": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false } }, "rounding": { "oneOf": [ { "type": "object", "required": [ "amount", "side", "account_public_id" ], "properties": { "amount": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "roundings": { "type": "array", "items": { "type": "object", "required": [ "amount", "side", "account_public_id" ], "properties": { "amount": { "type": "string" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "account_public_id": { "type": "string", "minLength": 26, "maxLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "cash_leg": { "type": "string", "enum": [ "sold", "bought", "fees" ], "description": "Present when the preview associates this rounding with an actual bank leg." } }, "additionalProperties": false }, "description": "All separately proven rounding amounts in this journal; a joint settlement may contain more than one. The scalar rounding field remains a compatibility projection of the first item." }, "heading": { "type": "string" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "additionalProperties": false, "description": "Existing periodic cash valuation journal shown alongside a manual journal proposal." }, "JournalRemovalPreview": { "type": "object", "required": [ "expected_revision", "state_hash", "opening_items", "periodic_valuations" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "state_hash": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "opening_items": { "type": "array", "items": { "$ref": "#/components/schemas/JournalOpeningItemEffect" } }, "periodic_valuations": { "type": "array", "items": { "$ref": "#/components/schemas/JournalPeriodicValuation" } } } }, "JournalRemovalPreviewResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/JournalRemovalPreview" } } }, "PayrollRefundSourceKey": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}:[0-9A-HJKMNP-TV-Z]{26}$", "description": "The explicitly selected original payroll payment ULID, a colon, and payslip ULID; scoped to the source administration." }, "BankPayrollRefundInput": { "type": "object", "additionalProperties": false, "properties": { "channel": { "type": "string", "enum": [ "bank", "cash", "rekening_courant", "linked_administration" ] }, "receiving_administration_public_id": { "$ref": "#/components/schemas/Ulid" }, "ledger_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "payer_contact_public_id": { "$ref": "#/components/schemas/Ulid", "description": "Required only for current-account settlements: the explicitly selected existing contact of the own or a linked administration, independently of the supplier. The complete configured route and current write access to every involved administration are required." }, "refund_date": { "type": "string", "format": "date" }, "amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "credit_currency_amount": { "$ref": "#/components/schemas/PurchaseDecimal" }, "fx": { "$ref": "#/components/schemas/PurchasePaymentFxInput" }, "route_configuration_public_ids": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/Ulid" } }, "edge_amounts": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/PurchaseRouteEdgeAmountInput" } }, "payroll_source_key": { "$ref": "#/components/schemas/PayrollRefundSourceKey" } }, "required": [ "payroll_source_key", "channel", "refund_date", "amount" ] }, "PayrollRefundOrigin": { "type": "object", "additionalProperties": false, "required": [ "source_key", "original_payment_public_id", "document_public_id", "beneficiary_public_id", "liability_account_public_id", "currency_code", "amount", "base_carrying_amount" ], "properties": { "source_key": { "$ref": "#/components/schemas/PayrollRefundSourceKey" }, "original_payment_public_id": { "$ref": "#/components/schemas/Ulid" }, "document_public_id": { "$ref": "#/components/schemas/Ulid" }, "beneficiary_public_id": { "$ref": "#/components/schemas/Ulid" }, "liability_account_public_id": { "$ref": "#/components/schemas/Ulid" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string" }, "base_carrying_amount": { "type": "string" } } } }, "responses": { "DeletedIdempotencyReplay": { "description": "A completed Post/Edit command whose target was later deleted. No command is re-executed; only the permanently redacted tombstone is replayed.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeletedJournalEntryResponse" }, { "$ref": "#/components/schemas/FxRevaluationResponse" }, { "$ref": "#/components/schemas/CurrentAccountDataResponse" }, { "$ref": "#/components/schemas/SalesDocumentTombstoneResponse" }, { "$ref": "#/components/schemas/SalesSettlementTombstoneResponse" } ] } } } }, "Unauthenticated": { "description": "Missing, invalid, revoked or expired bearer token.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "API-authenticatie is vereist.", "details": {} }, "request_id": "01J00000000000000000000000" } } } }, "AbilityNotAllowed": { "description": "The token lacks the ability required by this endpoint; error.code is ability_not_allowed.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "The authenticated principal is not authorized; error.code is forbidden.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ForbiddenOrAbilityNotAllowed": { "description": "The token lacks the required ability (ability_not_allowed) or the current role/policy forbids the action (forbidden).", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ability_not_allowed": { "value": { "error": { "code": "ability_not_allowed", "message": "Het token staat deze actie niet toe.", "details": {} }, "request_id": "01J00000000000000000000000" } }, "forbidden": { "value": { "error": { "code": "forbidden", "message": "Je mag deze actie niet uitvoeren.", "details": {} }, "request_id": "01J00000000000000000000000" } } } } } }, "NotFound": { "description": "The requested API resource does not exist. Scoped financial lookups use journal_entry_not_found, ledger_account_not_found or opening_balance_not_found; other missing resources use resource_not_found.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "SalesSettlementNotFound": { "description": "The scoped sales document or settlement does not exist. error.code is sales_document_not_found or sales_settlement_not_found.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementErrorEnvelope" } } } }, "OpeningBalanceNotFound": { "description": "No operational opening balance exists; error.code is opening_balance_not_found.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "opening_balance_not_found", "message": "De beginbalans is niet gevonden.", "details": {} }, "request_id": "01J00000000000000000000000" } } } }, "BusinessConflict": { "description": "The request conflicts with current business state. Financial codes include journal_entry_deleted, journal_entry_stale, fiscal_year_closed, fiscal_year_closing_unbalanced, ledger_account_inactive, fiscal_year_has_journal_entries, fiscal_year_boundary_conflicts_with_journal_entries and idempotency_key_reused. Existing reachable codes include fiscal_year_already_closed, fiscal_year_already_open, fiscal_year_not_ended, fiscal_year_close_order_invalid, fiscal_year_boundary_requires_open_years, fiscal_year_last_remaining, ledger_account_code_already_exists, ledger_account_already_active, ledger_account_already_inactive, ledger_account_classification_locked, ledger_account_normal_balance_locked, ledger_account_in_use and administration_not_active.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "FxStateConflict": { "description": "Foreign-currency state changed after preview. error.code is fx_position_state_stale, fx_rate_set_stale, fx_settlement_evidence_stale or fx_revaluation_stale. Re-run the corresponding preview and retry with a new Idempotency-Key.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "SalesSettlementConflict": { "description": "The sales document, receipt, refund or correction conflicts with current Sales, route, open-year, VAT, FX or idempotency state. error.code is one of the stable SalesSettlementErrorCode values appropriate to HTTP 409.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementErrorEnvelope" } } } }, "SalesSettlementValidationFailed": { "description": "Invalid receipt, refund, correction, account-derived currency, allocation, exchange-rate evidence or payment-difference choice. error.code is one of the stable SalesSettlementErrorCode values appropriate to HTTP 422.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesSettlementErrorEnvelope" } } } }, "ValidationFailed": { "description": "Invalid request input or domain validation. Financial codes include journal_entry_minimum_lines, journal_entry_too_many_lines, journal_entry_unbalanced, journal_entry_invalid_amount, posting_date_invalid, posting_date_outside_fiscal_calendar, idempotency_key_required and idempotency_key_invalid. Existing FiscalYear codes include fiscal_year_dates_invalid, fiscal_year_calendar_gap, fiscal_year_calendar_overlap, fiscal_year_future_limit_reached and fiscal_year_boundary_invalid. Ledger-account requests enforce an uppercase alphanumeric code, a known reporting classification and an optional active level-4 RGS reference; structural Laravel validation uses validation_failed.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InternalError": { "description": "Internal error without implementation details; error.code is internal_error.", "headers": { "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "tags": [ { "name": "Loans", "description": "Loan registers, schedules and accounting. Balances are derived from ledger entries and opening balances." } ] }