LIABILITY_UPLOAD category is allowed (the documents are automatically moved to LIABILITIES when the booking is created successfully via POST /core/v1/bookings). The GUI implementation of booking creation must therefore always pass LIABILITY_UPLOAD as the category value in the request body.",
"operationId": "uploadCompanyDocument",
"parameters": [
{
"name": "company-id",
"in": "path",
"description": "Identifier of the company that owns the document. Must match the company id carried by the bearer token, otherwise the request is rejected with 403.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"nullable": false
}
}
],
"requestBody": {
"description": "Multipart body with two parts: 'category' (text) and 'file' (binary, ≤ 25 MB).",
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/CompanyDocumentUploadForm"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Document successfully uploaded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documentId": {
"description": "Identifier of the stored document, assigned by the document service.",
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"413": {
"description": "Uploaded file exceeds the 25 MB limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"415": {
"description": "Unsupported Media Type"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/company-configuration/including-vat": {
"get": {
"tags": [
"Company general"
],
"summary": "Get the VAT inclusion setting for the authenticated company.",
"description": "Returns whether invoice amounts for the company resolved from the bearer JWT are displayed and calculated including VAT (includingVat: true) or excluding VAT (includingVat: false). Use this value before creating or displaying invoices to apply the correct pricing model. When no configuration record exists for the company, the endpoint returns false (excluding VAT) as the default. The caller must hold the FINANCE permission on the target company.",
"responses": {
"200": {
"description": "VAT inclusion setting for the authenticated company.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompanyConfigurationIncludingVatResult"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/company-vats": {
"get": {
"tags": [
"Company general"
],
"summary": "Returns vat list of a company",
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Company vats",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyVAT"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/customers": {
"get": {
"tags": [
"Customer"
],
"summary": "Returns all customers of a company",
"responses": {
"200": {
"description": "Customers",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Customer"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Customer"
],
"summary": "Create a new customer",
"requestBody": {
"description": "The customer object with the information that needs to be created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Customer created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/customers/{customer-id}": {
"get": {
"tags": [
"Customer"
],
"summary": "Returns a customer of a company based on given id",
"parameters": [
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"responses": {
"200": {
"description": "Found Customer",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Customer"
],
"summary": "Update an existing customer",
"parameters": [
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer to be updated",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"requestBody": {
"description": "The customer object with the information that needs to be updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Customer updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Customer"
],
"summary": "Delete a customer",
"parameters": [
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer to be deleted",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"responses": {
"204": {
"description": "Customer deleted"
},
"400": {
"description": "Could not delete Customer that contain orders",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/customers/{customer-id}/additional-addresses": {
"get": {
"tags": [
"Customer"
],
"summary": "Gets all additional addresses of a customer",
"parameters": [
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer to get additional addresses",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"responses": {
"200": {
"description": "List of all additional addresses",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Address"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Customer"
],
"summary": "Creates a new customer's additional address",
"parameters": [
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer to add additional addresses to",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"requestBody": {
"description": "The additional address object with the information that needs to be created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Customer's new additional address created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/customers/{customer-id}/additional-addresses/{address-id}": {
"put": {
"tags": [
"Customer"
],
"summary": "Updates a Address",
"operationId": "update additional-addresses",
"parameters": [
{
"name": "address-id",
"in": "path",
"description": "The id of the requested Address",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
},
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer needed to update an additional address",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"requestBody": {
"description": "The Address object with the information that needs to be updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Updated additional-addresses",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Customer"
],
"summary": "Delete an additional-address data by customer's id and customer's contact-id",
"operationId": "delete additional-address",
"parameters": [
{
"name": "address-id",
"in": "path",
"description": "Id of the additional address needed to be updated",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
},
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer to update an additional address deleted",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"responses": {
"204": {
"description": "Additional-address deleted"
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/customers/{customer-id}/contacts": {
"get": {
"tags": [
"Customer"
],
"summary": "Gets all contacts of a customer",
"parameters": [
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer to get all contacts from",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"responses": {
"200": {
"description": "List of contacts",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomerContact"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Customer"
],
"summary": "Creates a new customer's contact",
"parameters": [
{
"name": "customer-id",
"in": "path",
"description": "The id of the requested customer to add new contact to",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"requestBody": {
"description": "The CustomerContact object with the information that needs to be created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerContact"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Customer's new contact created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerContact"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/customers/{customer-id}/contacts/{contact-id}": {
"put": {
"tags": [
"Customer"
],
"summary": "Updates a CustomerContact",
"operationId": "update CustomerContact",
"parameters": [
{
"name": "contact-id",
"in": "path",
"description": "The id of the requested customer's contact to be updated",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
},
{
"name": "customer-id",
"in": "path",
"description": "Id of the customer to have a contact updated",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"requestBody": {
"description": "The customer's contact object with the information that needs to be updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerContact"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Updated contact",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerContact"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"Customer"
],
"summary": "Delete a CustomerContact data by customer's id and customer's contact-id",
"operationId": "delete CustomerContact",
"parameters": [
{
"name": "contact-id",
"in": "path",
"description": "Id of a customer's contact to be deleted",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
},
{
"name": "customer-id",
"in": "path",
"description": "Id of the requested customer to have a contact deleted",
"required": true,
"schema": {
"type": "string",
"example": "1"
}
}
],
"responses": {
"204": {
"description": "Customer's contact deleted"
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/latest/generic-token": {
"post": {
"tags": [
"Klara authentication generic"
],
"summary": "Generate tokens to use Klara specific endpoint",
"description": "Use this endpoint to get the access token for a specific user, and refresh token. Each subscription is subjective to its own terms and conditions. Please ask your KLARA contacts or see more details using the KLARA webclient.
", "parameters": [ { "name": "marketing-code", "in": "query", "description": "Marketing code to identify which product will be subscribed. The marketing codes to create subscriptions for.", "schema": { "type": "array", "items": { "type": "string" } }, "example": "K-01-0002-00-M" } ], "responses": { "201": { "description": "Subscription created successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } } } }, "400": { "description": "Invalid subscription data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The user has been disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "API rate limit exceeded" }, "500": { "description": "Something went wrong when creating subscriptions for the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/core/latest/tenants": { "post": { "tags": [ "Authentication" ], "summary": "Returns all tenants of a user", "description": "A Klara user might have multiple tenants. Use this endpoint to get the list of tenants containing tenant id, company id.legal-form query parameter is supplied, only accounts that carry a translation for that legal form are returned, and the name field is resolved from the legal-form-specific translation column. The Accept-Language header selects which translation is used; if absent or unsupported the platform default applies. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.",
"parameters": [
{
"name": "legal-form",
"in": "query",
"description": "Restricts the result to accounts that carry a translation for the given Swiss legal form, and resolves name from that legal-form-specific column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.",
"schema": {
"enum": [
"LIMITED_LIABILITY",
"CORPORATION",
"OR",
"INDIVIDUALLY_OWNED_COMPANY",
"ASSOCIATION",
"SIMPLE_PARTNERSHIP",
"GENERAL_PARTNERSHIP",
"LIMITED_PARTNERSHIP",
"COOPERATIVE_COMPANY",
"FOUNDATION"
],
"type": "string",
"example": "CORPORATION"
},
"example": "CORPORATION"
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to resolve the localized name field of each account. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Master accounts, sorted by code ascending. Empty array when the chart of accounts has not been seeded yet.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiAccount"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"404": {
"description": "The supplied legal-form value does not match any known legal form.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/accounts/account-displaying": {
"get": {
"tags": [
"Accounting"
],
"summary": "List the account-displaying picker rows for the authenticated company.",
"description": "Returns a flat list of AccountDisplaying rows for every account in the caller's company chart of accounts. Each row represents one selectable combination that a bookkeeper can pick when entering a manual journal line. Tenant and company are derived from the bearer token — there are no tenant or company path parameters.How rows are produced: For each master account the downstream service checks whether the account carries any linked sub-account definitions (e.g. a bank account linked to specific bank-accounts, a VAT account linked to VAT-rate items). If the account has no sub-account definitions, exactly one bare row is emitted with combinedCode equal to the bare account code (e.g. \"3000\"), linkType equal to null, and specificationItem equal to null. If the account has one or more sub-account link specifications, one row is emitted per individual sub-account entry, numbered sequentially across all link types with a 0-based counter suffix: \"1020-0\", \"1020-1\", …
combinedCode: \"<accountCode>-<i>\" when a sub-account exists (e.g. \"1020-0\"), or the bare account code string (e.g. \"3000\") when linkType is null. The suffix index is a flat 0-based counter per account, spanning all link types in declaration order.
combinedName: \"<accountName> (<subAccountDisplay>)\" when a sub-account exists (e.g. \"Bank (UBS)\"), or the bare account name (e.g. \"Bürobedarf\") when linkType is null.
parentAccount: the full master account this row belongs to. Always populated, including for bare rows.
linkType: the link-type category name (e.g. \"BANK\", \"CUSTOMER\", \"VAT_RATE\"). null when the account has no sub-account definitions.
linkDisplay: the human-readable label for the link type in the current locale (e.g. \"Bank account\"). Falls back to the German label when no translation exists for the requested language. null when linkType is null.
linkOptional: true when the sub-account selection is optional for the user (link keys are separated by ; in the account definition); false when selecting a sub-account is mandatory (link keys separated by ,); null when the account has no sub-account definitions.
specificationItem: the resolved sub-account entry for this row. Its link field is the URI that must be round-tripped back to the booking endpoint when the user selects this row. Its display field is the human-readable label shown to the bookkeeper (e.g. \"UBS\", \"8.1 %\"). null when linkType is null.
Row order is stable: accounts are sorted by code ascending (same order as GET /core/v1/accounting/accounts); sub-account rows within each account preserve the link-type declaration order and then the entry order returned by the underlying service.
ACCOUNTING permission on the company in scope.",
"parameters": [
{
"name": "legal-form",
"in": "query",
"description": "When supplied, restricts the result to accounts that carry a translation for the given Swiss legal form and resolves the parentAccount.name field from the legal-form-specific translation column. When omitted, all accounts are returned and account.name is resolved from the generic language column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.",
"schema": {
"enum": [
"LIMITED_LIABILITY",
"CORPORATION",
"OR",
"INDIVIDUALLY_OWNED_COMPANY",
"ASSOCIATION",
"SIMPLE_PARTNERSHIP",
"GENERAL_PARTNERSHIP",
"LIMITED_PARTNERSHIP",
"COOPERATIVE_COMPANY",
"FOUNDATION"
],
"type": "string",
"example": "CORPORATION"
},
"example": "CORPORATION"
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to localize the parentAccount.name field of each row and the linkDisplay label. Falls back to German when no translation exists for the requested language. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Flat list of account-displaying rows, sorted by account code ascending. Each row contains combinedCode, combinedName, parentAccount, and the link fields populated for sub-account rows or null for bare rows. Returns an empty array when no accounts match the supplied legal-form.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiAccountDisplaying"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "The company associated with the caller's session could not be resolved by the downstream accounting service, or the supplied legal-form value does not match any known legal form.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/accounts/by-code/{accountCode}": {
"get": {
"tags": [
"Accounting"
],
"summary": "Resolve a Klara master account by its chart-of-account code.",
"description": "Loads a single master account row from Klara's global chart of accounts, identified by its numeric accountCode. The data is global — the same chart of accounts is shared across every tenant, so there are no tenant or company path parameters. When the optional legal-form query parameter is supplied, the name field is resolved from the legal-form-specific translation column instead of the generic one. The Accept-Language header selects which translation is used; if absent or unsupported the platform default applies. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.",
"parameters": [
{
"name": "accountCode",
"in": "path",
"description": "Numeric chart-of-account code as printed on the Klara master chart of accounts (e.g. 1000 for cash, 6000 for material expense).",
"required": true,
"schema": {
"type": "string",
"example": "6000"
},
"example": 6000
},
{
"name": "legal-form",
"in": "query",
"description": "When supplied, resolves name from the legal-form-specific translation column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.",
"schema": {
"enum": [
"LIMITED_LIABILITY",
"CORPORATION",
"OR",
"INDIVIDUALLY_OWNED_COMPANY",
"ASSOCIATION",
"SIMPLE_PARTNERSHIP",
"GENERAL_PARTNERSHIP",
"LIMITED_PARTNERSHIP",
"COOPERATIVE_COMPANY",
"FOUNDATION"
],
"type": "string",
"example": "CORPORATION"
},
"example": "CORPORATION"
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to resolve the localized name field of the account. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "The master account matching accountCode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiAccount"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"404": {
"description": "No master account exists for the supplied accountCode, or the supplied legal-form value does not match any known legal form.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/booking-types": {
"get": {
"tags": [
"Accounting"
],
"summary": "List Klara master accounting booking types.",
"description": "Returns the canonical catalog of accounting booking types maintained by Klara — the stable set of bookkeeping operations (general-ledger postings, payable / receivable invoices, payments, credit notes, prepayments, amortizations, delimitations) that every Klara company can post against. The data is global — the same catalog is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation of the human-readable description is returned; if absent or unsupported the German translation is used as a fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.",
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to resolve the localized description of each booking type. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Master booking types, ordered by code ascending. Empty array when the catalog has not been seeded yet.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiBookingType"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/business-case-templates": {
"get": {
"tags": [
"Accounting"
],
"summary": "List Klara master accounting business-case templates.",
"description": "Returns the global catalog of business-case templates — the manual-journal categories that drive the booking form (operating expenses, salary payments, asset purchases, …). The catalog is global Klara reference data: the same list is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation of the human-readable display label is returned; if absent or unsupported the German translation is used as a fallback and the full per-language i18n / keywordI18ns maps are returned for client-side rendering. Optional orderColumns / offset / limit query parameters are forwarded verbatim to the downstream catalog for ordering and pagination. The endpoint is a pure read — idempotent, no side effects. Requires a bearer token whose principal carries the ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE permission.",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Maximum number of templates to return. When omitted, the downstream service returns the full catalog.",
"required": false,
"schema": {
"type": "integer",
"example": 50
},
"example": 50
},
{
"name": "offset",
"in": "query",
"description": "Zero-based index of the first template to return. When omitted, the response starts at the first row.",
"required": false,
"schema": {
"type": "integer",
"example": 0
},
"example": 0
},
{
"name": "orderColumns",
"in": "query",
"description": "Names of columns to order the result by, ascending. Repeat the query parameter for multi-column ordering (e.g. ?orderColumns=group&orderColumns=code).",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"example": "code"
},
"example": "code"
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to resolve the localized display label of each template. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Business-case templates matching the supplied ordering and pagination.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiBusinessCaseTemplate"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/business-case-templates/{businessCaseTemplateId}": {
"get": {
"tags": [
"Accounting"
],
"summary": "Read a single Klara master accounting business-case template by id.",
"description": "Returns one business-case template from the global Klara catalog — a manual-journal category usable when entering a booking (for example operating expenses, salary payments, asset purchases). The catalog is global Klara reference data, so this endpoint has no tenant or company path parameters; only the catalogue id selects the template. The Accept-Language header selects which translation of the human-readable display label is returned; if absent or unsupported the German translation is used as a fallback and the full per-language i18n / keywordI18ns maps are returned for client-side rendering. The endpoint is a pure read — idempotent, no side effects. Returns 404 when no template with the requested id exists in the catalog. Requires a bearer token whose principal carries the ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE permission.",
"parameters": [
{
"name": "businessCaseTemplateId",
"in": "path",
"description": "Numeric primary-key id of the business-case template in the Klara master catalog. Obtain it from a prior call to GET /core/v1/accounting/business-case-templates.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"example": 101
},
"example": 101
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to resolve the localized display label of the template. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Business-case template matching the supplied id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiBusinessCaseTemplate"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "No business-case template carries the requested id."
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/business-cases": {
"get": {
"tags": [
"Accounting"
],
"summary": "Hydrate a business case from a template id for the authenticated company.",
"description": "Loads the fully hydrated business-case aggregate the booking form needs: the template id, the company-VAT and fiscal-year context resolved from the optional date filters, the pre-translated display label, and the recursive snippet / field tree. When dateForFilteringFiscalYear is supplied it drives the fiscal-year resolution; otherwise dateForFilteringCompanyVat is used; otherwise the downstream service resolves the fiscal year that covers today. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.",
"parameters": [
{
"name": "businessCaseTemplateId",
"in": "query",
"description": "Numeric id of the business-case template to hydrate. Obtain it from GET /core/v1/accounting/companies/current/business-case-templates.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"example": 101
},
"example": 101
},
{
"name": "dateForFilteringCompanyVat",
"in": "query",
"description": "ISO date (yyyy-MM-dd) used to resolve the company-VAT regime applicable to the business case. Used as the fallback for dateForFilteringFiscalYear when that is omitted.",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2024-06-15"
},
"example": "2024-06-15"
},
{
"name": "dateForFilteringFiscalYear",
"in": "query",
"description": "ISO date (yyyy-MM-dd) used to resolve the fiscal year that hydrates the business case. When omitted, falls back to dateForFilteringCompanyVat; when both are omitted the downstream service resolves the fiscal year that covers today.",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2024-06-15"
},
"example": "2024-06-15"
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Hydrated business-case aggregate for the requested template.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiBusinessCase"
}
}
}
},
"400": {
"description": "One of dateForFilteringFiscalYear / dateForFilteringCompanyVat is not a valid ISO date (yyyy-MM-dd), or the supplied businessCaseTemplateId is not valid for the company's legal form or VAT regime.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "No business-case template matches the supplied businessCaseTemplateId in the caller's company scope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/business-cases/{businessCaseId}": {
"get": {
"tags": [
"Accounting"
],
"summary": "Read a persisted business-case instance by its id for the authenticated company.",
"description": "Loads the fully hydrated business-case aggregate that was previously persisted for the authenticated company: the template id, the company-VAT and fiscal-year context that were in force when the case was booked, the pre-translated display label, the recursive snippet / field tree with the persisted scripted values overlaid, and the comma-separated list of booking numbers already generated for it. Tenant and company are derived from the bearer-token session — they are never accepted from the URL; the supplied businessCaseId is matched against the caller's company so that an id owned by another company surfaces as 404. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.",
"parameters": [
{
"name": "businessCaseId",
"in": "path",
"description": "Numeric primary-key id of the persisted business-case instance to hydrate. Obtain it from a prior booking response (for example POST /core/v1/accounting/bookings) or from a journal listing.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"example": 5001
},
"example": 5001
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Hydrated business-case aggregate for the requested id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiBusinessCase"
}
}
}
},
"400": {
"description": "The supplied businessCaseId is not a valid numeric id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "No business case matches the supplied businessCaseId in the caller's company scope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/business-cases/v2": {
"get": {
"tags": [
"Accounting"
],
"summary": "Hydrate a business case from a template id, scoped to a single snippet.",
"description": "Snippet-scoped variant of GET /core/v1/accounting/business-cases: hydrates only the template root plus the snippet identified by snippet-id, so the booking UI can stream the form one snippet at a time instead of loading the whole tree up-front. When dateForFilteringFiscalYear is supplied it drives the fiscal-year resolution; otherwise dateForFilteringCompanyVat is used; otherwise the downstream service resolves the fiscal year that covers today. When group-insurance-by-insurer is true (the default), social-insurance entries that share the same display + value pair are collapsed, keeping the entry with the smallest numeric id. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.",
"parameters": [
{
"name": "businessCaseTemplateId",
"in": "query",
"description": "Numeric id of the business-case template to hydrate. Obtain it from GET /core/v1/accounting/companies/current/business-case-templates.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"example": 101
},
"example": 101
},
{
"name": "dateForFilteringCompanyVat",
"in": "query",
"description": "ISO date (yyyy-MM-dd) used to resolve the company-VAT regime applicable to the business case. Used as the fallback for dateForFilteringFiscalYear when that is omitted.",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2024-06-15"
},
"example": "2024-06-15"
},
{
"name": "dateForFilteringFiscalYear",
"in": "query",
"description": "ISO date (yyyy-MM-dd) used to resolve the fiscal year that hydrates the business case. When omitted, falls back to dateForFilteringCompanyVat; when both are omitted the downstream service resolves the fiscal year that covers today.",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2024-06-15"
},
"example": "2024-06-15"
},
{
"name": "group-insurance-by-insurer",
"in": "query",
"description": "When true, collapses social-insurance entries that share the same display + value pair, keeping the entry with the smallest numeric id. Defaults to true. Allowed values: true, false.",
"required": false,
"schema": {
"default": "true",
"type": "boolean",
"example": true
},
"example": true
},
{
"name": "snippet-id",
"in": "query",
"description": "Numeric id of the snippet currently activated by the user; v2 hydrates only this snippet plus the template root. When omitted, only the template root is hydrated.",
"required": false,
"schema": {
"format": "int64",
"type": "integer",
"example": 42
},
"example": 42
},
{
"name": "snippet-value",
"in": "query",
"description": "Currently ignored on the downstream side; reserved for a future optimisation that would load external entries only for the activated value (for example, payment dates of a single employee). Safe to omit.",
"required": false,
"schema": {
"type": "string",
"example": "EMP-1001"
},
"example": "EMP-1001"
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Hydrated business-case aggregate for the requested template and snippet.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiBusinessCase"
}
}
}
},
"400": {
"description": "One of dateForFilteringFiscalYear / dateForFilteringCompanyVat is not a valid ISO date (yyyy-MM-dd), or the supplied businessCaseTemplateId is not valid for the company's legal form or VAT regime.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "No business-case template matches the supplied businessCaseTemplateId in the caller's company scope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/companies/current": {
"get": {
"tags": [
"Accounting"
],
"summary": "Get the accounting configuration of the authenticated company.",
"description": "Returns the dunning waiting periods configured for the authenticated caller's company together with the canonical compensation-side company URI. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. When the company has no accounting configuration row persisted yet, the downstream service synthesises a default record (id = null, waitingDunningTime = 5, dunningWaitingTimeLevelOne / Two / Three = 10) so the response shape stays the same. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.",
"responses": {
"200": {
"description": "Accounting configuration of the caller's company.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiAccountingCompany"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "The company associated with the caller's session could not be resolved by the downstream accounting service.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/companies/current/business-case-templates": {
"get": {
"tags": [
"Accounting"
],
"summary": "List business-case templates available to the authenticated company, grouped by financial-year period.",
"description": "Returns the manual-journal categories (\"business-case templates\") the caller's company is allowed to book against, grouped by the financial-year period in which they are valid. Each period carries its periodFrom / periodTo, the company's legalForm and active VAT regime, and the templates that pass the legal-form / VAT-regime filters for that period. Templates are sorted by code; the display field is pre-translated using the Accept-Language header and the full per-language map is also returned in i18n / keywordI18ns. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.",
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to translate the display field of each template. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Business-case templates grouped by financial-year period. May be an empty array when the company has no open fiscal year yet.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiBusinessCasePeriod"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "The company associated with the caller's session could not be resolved by the downstream accounting service.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/companies/current/financial-years": {
"get": {
"tags": [
"Accounting"
],
"summary": "List active financial-year periods of the authenticated company.",
"description": "Returns the company's currently active fiscal-year periods (status OPEN or CLOSING), one entry per legal-form / VAT-regime combination valid in the period. When every period shares the same legalForm and VAT regime the downstream service collapses them into a single aggregated period with periodFrom set to the earliest start date and periodTo set to the latest end date; otherwise the individual periods are returned. The businessCaseTemplates field is intentionally left empty on this endpoint — use GET /core/v1/accounting/companies/current/business-case-templates to retrieve the templates valid per period. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.",
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag forwarded to the downstream accounting service. Examples: de-CH, fr-CH, it-CH, en.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Active financial-year periods of the caller's company. May be an empty array when the company has no open fiscal year yet.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiBusinessCasePeriod"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "The company associated with the caller's session could not be resolved by the downstream accounting service.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/currencies/exchange-rate": {
"get": {
"tags": [
"Accounting"
],
"summary": "Get the CHF exchange rate for a currency on a given date.",
"description": "Returns the Swiss National Bank reference rate that converts one unit of from-currency-code into CHF on exchange-date. When from-currency-code equals CHF (case-insensitive) the rate is always 1. The exchange-rate table is global SNB data — the same response is returned for every tenant, so there are no tenant or company path parameters. If no rate is stored for the requested day, the downstream service transparently fetches the SNB feed for that date and persists the result; if the feed has no entry either, the most recent rate strictly before exchange-date is returned instead. The endpoint is a pure read for the caller — idempotent. Requires a bearer token whose principal carries the ACCOUNTING permission.",
"parameters": [
{
"name": "exchange-date",
"in": "query",
"description": "Reference date for the exchange rate, expressed as an ISO-8601 calendar date (yyyy-MM-dd).",
"required": true,
"schema": {
"format": "date",
"type": "string",
"example": "2024-09-30"
},
"example": "2024-09-30"
},
{
"name": "from-currency-code",
"in": "query",
"description": "ISO-4217 alpha-3 currency code of the source amount. Case-insensitive; CHF short-circuits to a rate of 1.",
"required": true,
"schema": {
"type": "string",
"example": "EUR"
},
"example": "EUR"
}
],
"responses": {
"200": {
"description": "Exchange rate as a JSON number; the value 1 when from-currency-code is CHF.",
"content": {
"application/json": {
"schema": {
"type": "number",
"example": 0.9421
}
}
}
},
"400": {
"description": "exchange-date is not a valid ISO-8601 calendar date, or no rate could be resolved for the supplied from-currency-code.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/master-vats": {
"get": {
"tags": [
"Accounting"
],
"summary": "List the master VAT catalog used by Klara Accounting.",
"description": "Returns the global master VAT catalog — the table of supported VAT rates with their validity ranges and translated labels. The downstream handler is a dispatcher driven by the query string: when code is non-blank only rows whose vatCode matches one of the semicolon-separated codes are returned (and when combined with current-period=true, only the ones valid today); otherwise when default-vat=true only the company-default rows are returned; otherwise the full catalog is returned, ordered by rate ascending, optionally paginated via offset / limit. Pagination is honoured only on the full-catalog branch — it is silently ignored when code or default-vat is set. The endpoint is a pure read and idempotent. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.",
"parameters": [
{
"name": "code",
"in": "query",
"description": "Semicolon-separated list of vatCodes to filter on. When set, switches the response to the by-code branch and ignores default-vat.",
"required": false,
"schema": {
"type": "string",
"example": "1;3;4"
},
"example": "1;3;4"
},
{
"name": "current-period",
"in": "query",
"description": "When combined with code, restricts the result to master VAT rows whose validity range covers today. Defaults to false.",
"required": false,
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "default-vat",
"in": "query",
"description": "When true, restricts the result to the company-default master VAT rows. Defaults to false. Ignored when code is set.",
"required": false,
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "includeHiddenVatCase",
"in": "query",
"description": "When true, the response also includes hidden VAT-case ids that are not directly mapped to a master VAT row. Defaults to false.",
"required": false,
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of results to return. Only honoured on the full-catalog branch.",
"required": false,
"schema": {
"type": "integer",
"example": 50
},
"example": 50
},
{
"name": "offset",
"in": "query",
"description": "Zero-based index of the first result. Only honoured on the full-catalog branch (when neither code nor default-vat is set).",
"required": false,
"schema": {
"type": "integer",
"example": 0
},
"example": 0
}
],
"responses": {
"200": {
"description": "Array of master VAT rows matching the filters.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiMasterVat"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/master-vats/{masterVatId}": {
"get": {
"tags": [
"Accounting"
],
"summary": "Resolve a master VAT catalog row by its numeric id.",
"description": "Loads a single master VAT row from Klara's global master VAT catalog, identified by its numeric primary-key masterVatId. The catalog is global Klara reference data — the same row is returned for every tenant, so there are no tenant or company path parameters. The endpoint is a pure read and idempotent. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.",
"parameters": [
{
"name": "masterVatId",
"in": "path",
"description": "Numeric primary-key id of the master VAT row to resolve. Obtain it from GET /core/v1/accounting/master-vats or GET /core/v1/accounting/master-vats/current.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"example": 12
},
"example": 12
}
],
"responses": {
"200": {
"description": "The master VAT row matching masterVatId, including its rate, VAT code and validity range.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiMasterVat"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"404": {
"description": "No master VAT row exists for the supplied masterVatId.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/master-vats/current": {
"get": {
"tags": [
"Accounting"
],
"summary": "List the master VAT rows valid for today.",
"description": "Returns the subset of the master VAT catalog whose validity range (validFrom / validTo) covers the server's current day. Useful for booking and invoicing UIs that need only the VAT rates that may legally be applied right now. The endpoint is a pure read and idempotent; the downstream handler caches the filtered list in-process. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.",
"responses": {
"200": {
"description": "Array of master VAT rows valid for the current day.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiMasterVat"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/vat-profile": {
"get": {
"tags": [
"Accounting"
],
"summary": "Get the authenticated company's VAT reporting profile.",
"description": "Returns the company's VAT regime (effective vs net-tax-rate), billing method and flat net-tax rates, so an integration knows when the Saldosteuersatz flat-rate layer applies.",
"parameters": [
{
"name": "date",
"in": "query",
"description": "Date (ISO yyyy-MM-dd) to resolve the company VAT config for; defaults to today. Use the date you intend to book on — the company VAT must be valid for it.",
"schema": {
"type": "string"
},
"example": "2025-05-08"
}
],
"responses": {
"200": {
"description": "VAT profile.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiVatProfile"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/vat-suggestions": {
"get": {
"tags": [
"Accounting"
],
"summary": "Suggest ready-to-use VAT case / rate / account bundles for a booking line.",
"description": "Turns a plain-language context — a purchase vs a sale — into ranked, copy-paste-ready VAT bundles. Each bundle carries the verbatim vatCaseLink and vatRateLink to drop into a booking line's links, plus a suggested vatAccountCode. Supply amount to also receive a net/VAT preview. The bundle marked recommended is the server's best guess.| GUI control | Driven by | How to build it |
|---|---|---|
| VAT on/off toggle | client-side state (not in this response) | OFF → the line has no VAT: don't call this endpoint, add no VAT links/fields. ON → call this endpoint and show the dropdowns below. |
| VAT case dropdown (e.g. \"taxable supply\") | distinct vatCaseCode (label it with label) | Group the array by vatCaseCode; one entry per distinct case. |
| VAT rate dropdown (e.g. \"8.1%\") | vatRateDisplay | Cascades from the chosen case: the rows sharing the selected vatCaseCode are the rate options. |
| VAT account dropdown (e.g. \"1170 | Input tax VAT\") | vatAccountCodes | List all vatAccountCodes; preselect vatAccountCode. |
| including / excluding toggle | the amountKind query param | including = GROSS_INCLUSIVE; excluding = NET_EXCLUSIVE. Flipping it means re-calling this endpoint to refresh the preview. |
| Debit / Credit amount preview | previewNet / previewVat | Null until you pass amount. Re-call with the new amount/amountKind to refresh. |
direction (PURCHASE/SALE), the line's accountCode, the user's amount, the amountKind from the including/excluding toggle, and the date you will book on.recommended = true.POST /core/v1/bookings?autoCalculateVat=true: on the VAT-bearing line set links = \"<vatCaseLink>,<vatRateLink>\" (both verbatim), vatAccountCode = <vatAccountCode>, your amount, and isExcludeVatAmount matching the amountKind you queried — then omit the VAT counterpart line; the server generates it (matching previewNet/previewVat). Pass the same date you will book on.direction), and the rate list includes every configured version of each rate code the case references — current and historical — so a line dated before a rate change still finds its rate.",
"parameters": [
{
"name": "accountCode",
"in": "query",
"description": "Main account being booked against (e.g. 1020); drives VAT-account resolution. Required.",
"required": true,
"schema": {
"format": "int32",
"type": "integer"
},
"example": 4000
},
{
"name": "amount",
"in": "query",
"description": "Amount to preview the net/VAT split for (optional).",
"schema": {
"type": "number"
},
"example": 1000
},
{
"name": "amountKind",
"in": "query",
"description": "GROSS_INCLUSIVE (default) or NET_EXCLUSIVE.",
"schema": {
"default": "GROSS_INCLUSIVE",
"type": "string"
},
"example": "GROSS_INCLUSIVE"
},
{
"name": "date",
"in": "query",
"description": "Date (ISO yyyy-MM-dd) to resolve the company VAT config for; defaults to today.",
"schema": {
"type": "string"
},
"example": "2025-05-08"
},
{
"name": "direction",
"in": "query",
"description": "PURCHASE (you are buying) or SALE (you are selling). Required. It does not restrict which VAT cases are returned (the full case list is always offered); it only selects the fallback VAT account — purchases vs sales — and the recommendation wording.",
"required": true,
"schema": {
"enum": [
"PURCHASE",
"SALE"
],
"type": "string"
},
"example": "PURCHASE"
},
{
"name": "vatCase",
"in": "query",
"description": "VAT case code to restrict suggestions to a single case; returns all its rate/account bundles (optional). Any valid case code is accepted regardless of direction — e.g. a sales case such as TAXABLE_SUPPLY can be requested with direction=PURCHASE.",
"schema": {
"enum": [
"TAXABLE_SUPPLY",
"SUPPLY_WITH_OPTION_ART_22",
"TAX_EXEMPT_SUPPLY",
"EXPORT",
"SUPPLY_ABROAD",
"EXCLUDED_SUPPLY",
"DECREASE_IN_PROFITS",
"INTERNAL_CONSUMPTION",
"SUBVENTION",
"CONTRIBUTIONS_DIVIDEND_DAMAGE_COMPENSION",
"DOMESTIC_PURCHASE",
"IMPORT_WITH_CUSTOMS",
"IMPORT_WITH_REVERSE_CHARGE",
"PURCHASE_ABROAD",
"TRANSFER_SUPPLY",
"MISCELLANEOUS",
"DE_TAXATION",
"MIXED_USE",
"REDUCTION",
"TAX_CREDIT_1050",
"TAX_CREDIT_1055_1056"
],
"type": "string"
},
"example": "DOMESTIC_PURCHASE"
},
{
"name": "Accept-Language",
"in": "header",
"description": "Preferred language for the bundle labels.",
"schema": {
"type": "string"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Ranked VAT suggestions.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiVatSuggestion"
}
},
"examples": {
"Domestic purchase (accountCode=4000, amount=1000, GROSS_INCLUSIVE)": {
"description": "Four rows across two VAT cases: three DOMESTIC_PURCHASE rates (the recommended 8.1%, plus 3.8% and 2.6%) and one ACQUISITION_TAX case. Group by vatCaseCode to build the VAT-case dropdown; rows within a case are the VAT-rate options.",
"value": [
{
"label": "DOMESTIC_PURCHASE — 8.10%",
"recommended": false,
"vatCaseCode": "DOMESTIC_PURCHASE",
"vatCaseLink": "vat_case:/luz_accounting/api/vat-cases/5",
"vatRateDisplay": "8.10%",
"vatRateLink": "vat_rate:/luz_accounting/api/master-vats/58",
"vatAccountCode": 1171,
"previewNet": 925.07,
"previewVat": 74.93
},
{
"label": "DOMESTIC_PURCHASE — 3.80%",
"recommended": false,
"vatCaseCode": "DOMESTIC_PURCHASE",
"vatCaseLink": "vat_case:/luz_accounting/api/vat-cases/5",
"vatRateDisplay": "3.80%",
"vatRateLink": "vat_rate:/luz_accounting/api/master-vats/7",
"vatAccountCode": 1171,
"previewNet": 963.39,
"previewVat": 36.61
},
{
"label": "DOMESTIC_PURCHASE — 2.60%",
"recommended": false,
"vatCaseCode": "DOMESTIC_PURCHASE",
"vatCaseLink": "vat_case:/luz_accounting/api/vat-cases/5",
"vatRateDisplay": "2.60%",
"vatRateLink": "vat_rate:/luz_accounting/api/master-vats/56",
"vatAccountCode": 2203,
"previewNet": 974.66,
"previewVat": 25.34
},
{
"label": "DOMESTIC_PURCHASE — 8.10%",
"recommended": false,
"vatCaseCode": "DOMESTIC_PURCHASE",
"vatCaseLink": "vat_case:/luz_accounting/api/vat-cases/5",
"vatRateDisplay": "8.10%",
"vatRateLink": "vat_rate:/luz_accounting/api/master-vats/58",
"vatAccountCode": 2202,
"previewNet": 925.07,
"previewVat": 74.93
}
]
}
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/vat-types": {
"get": {
"tags": [
"Accounting"
],
"summary": "List Klara master VAT-type catalogue rows.",
"description": "Returns every VAT-type row maintained by Klara — the canonical VAT codes that can participate in a booking together with their posting formulas. The data is global — the same catalogue is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation is used for the description and vatTypeShortName fields; if absent or unsupported, German is used as the fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.",
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to resolve the localized description and vatTypeShortName fields. Examples: de-CH, fr-CH, it-CH, en. When the header is missing or the language is unknown, the downstream service falls back to German.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Master VAT-type rows. Empty array when the catalogue has not been seeded yet.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiVatType"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/accounting/vat-types/{vatTypeId}": {
"get": {
"tags": [
"Accounting"
],
"summary": "Resolve a Klara master VAT-type row by its numeric id.",
"description": "Loads a single VAT-type row from Klara's global master VAT-type catalogue, identified by its numeric primary-key vatTypeId. The data is global — the same catalogue is shared across every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation is used for the description and vatTypeShortName fields; if absent or unsupported, German is used as the fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.",
"parameters": [
{
"name": "vatTypeId",
"in": "path",
"description": "Numeric primary-key id of the master VAT-type row to resolve. Obtain it from GET /core/v1/accounting/vat-types.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"example": 1
},
"example": 1
},
{
"name": "Accept-Language",
"in": "header",
"description": "IETF language tag used to resolve the localized description and vatTypeShortName fields. Examples: de-CH, fr-CH, it-CH, en. When the header is missing or the language is unknown, the downstream service falls back to German.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "The master VAT-type row matching vatTypeId, including its localized description, short name and posting formulas.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiVatType"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"404": {
"description": "No master VAT-type row exists for the supplied vatTypeId.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/bank-reconciliation/open-positions": {
"get": {
"tags": [
"Accounting"
],
"summary": "List the bank-reconciliation open positions of the authenticated company.",
"description": "Returns the list of open booking-detail positions (AR / AP invoices, payments, prepayments, credit notes, general-ledger entries) of the caller's company that match the supplied filters, enriched with partner-name display, business-case message id, computed open amount and a stable booking-detail URI. Used by the bank-reconciliation UI to populate the open-position picker for a selected bank or credit-card transaction. The action parameter selects the multi-condition combinator: search (default) is OR-of-conditions, filter is AND-of-conditions. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING_GET_OPEN_POSITION permission on the company in scope.",
"parameters": [
{
"name": "action",
"in": "query",
"description": "Multi-condition combinator. search (default) = OR-of-conditions; filter = AND-of-conditions.",
"required": false,
"schema": {
"default": "search",
"enum": [
"search",
"filter"
],
"type": "string",
"example": "filter"
},
"example": "filter"
},
{
"name": "booking-type-codes",
"in": "query",
"description": "Comma-separated list of booking-type codes to restrict to. Allowed values: GENERAL_LEDGER, AP_INVOICE, AP_PAYMENT, AR_INVOICE, AR_PAYMENT, AP_PREPAYMENT, AP_PREPAYUSE, AR_PREPAYMENT, AR_PREPAYUSE, AR_CREDITNOTE, AR_CREDITUSE, AP_CREDITNOTE, AP_CREDITUSE, AMORTIZATION, SELLOFF_AMORTIZATION, DELIMIT.",
"required": false,
"schema": {
"type": "string",
"example": "AR_PREPAYMENT,AR_CREDITNOTE"
},
"example": "AR_PREPAYMENT,AR_CREDITNOTE"
},
{
"name": "crdr-type",
"in": "query",
"description": "Restrict to credit (CR) or debit (DR) postings.",
"required": false,
"schema": {
"$ref": "#/components/schemas/PublicApiCrDrType"
},
"example": "CR"
},
{
"name": "credit-card-not-reconciled",
"in": "query",
"description": "When true, restricts to credit-card transactions still pending reconciliation.",
"required": false,
"schema": {
"type": "boolean",
"example": true
},
"example": true
},
{
"name": "general-search",
"in": "query",
"description": "Free-text search across description, partner name, document id and reference fields. Combined with the other filters using the mode selected by action.",
"required": false,
"schema": {
"maxLength": 256,
"type": "string",
"example": "Migros"
},
"example": "Migros"
},
{
"name": "invoice-date",
"in": "query",
"description": "Exact-match invoice (document) date filter (ISO date yyyy-MM-dd).",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2026-04-15"
},
"example": "2026-04-15"
},
{
"name": "partner",
"in": "query",
"description": "Klara partner URI to filter by. Format: /api/luz_person/api/{tenantId}/companies/{companyId}/partners/{partnerId}. Construct from the partner id returned by the public partner endpoints.",
"required": false,
"schema": {
"type": "string",
"example": "/api/luz_person/api/c60d31fa-f335-4957-872a-90b035632081/companies/1/partners/123"
},
"example": "/api/luz_person/api/c60d31fa-f335-4957-872a-90b035632081/companies/1/partners/123"
},
{
"name": "payment-date",
"in": "query",
"description": "Exact-match payment date filter (ISO date yyyy-MM-dd).",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2026-05-28"
},
"example": "2026-05-28"
},
{
"name": "payment-date-from",
"in": "query",
"description": "Inclusive lower bound of the payment-date range filter (ISO date yyyy-MM-dd).",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2026-01-01"
},
"example": "2026-01-01"
},
{
"name": "payment-date-to",
"in": "query",
"description": "Inclusive upper bound of the payment-date range filter (ISO date yyyy-MM-dd).",
"required": false,
"schema": {
"format": "date",
"type": "string",
"example": "2026-06-30"
},
"example": "2026-06-30"
},
{
"name": "position-status",
"in": "query",
"description": "Comma-separated list of open-position lifecycle statuses to restrict to. Allowed values: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED, CLEARED.",
"required": false,
"schema": {
"type": "string",
"example": "OPEN,PARTLY_CLEARED"
},
"example": "OPEN,PARTLY_CLEARED"
},
{
"name": "tags",
"in": "query",
"description": "Comma-separated list of tag names to filter by (free-form).",
"required": false,
"schema": {
"maxLength": 256,
"type": "string",
"example": "vendor-x,q2"
},
"example": "vendor-x,q2"
}
],
"responses": {
"200": {
"description": "List of open positions matching the filters. Empty array when nothing matches.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiSuitableOpenPosition"
}
}
}
}
},
"400": {
"description": "One of the date filters is not a valid ISO date (yyyy-MM-dd), or one of the enum filters (position-status, booking-type-codes, crdr-type) carries a value that is not in the documented value set, or a free-text filter exceeds 256 characters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/bookings": {
"post": {
"tags": [
"Accounting"
],
"summary": "Create a new manual booking for the authenticated company.",
"description": "Records a manual journal entry against the authenticated caller's company and returns the persisted booking with its server-assigned identifiers. The booking must contain at least two debit/credit lines whose totals balance — the downstream service rejects unbalanced postings. By default the bookingDate must fall inside an open fiscal year; set confirmDontMindClosingFiscalYear to true to accept a booking that targets a closing fiscal year. Set ignore-unsubscripted-dates to true to bypass the subscription-period guard that normally rejects bookings outside the active Klara Accounting subscription window. Tenant and company are derived from the bearer token — the request body's id and companyId are ignored. The caller must hold the ACCOUNTING permission on the targeted company.",
"parameters": [
{
"name": "autoCalculateVat",
"in": "query",
"description": "When true, the server recalculates VAT like the Manual booking GUI: each VAT-bearing line sends a single gross/net amount + a vat_rate link + vatAccountCode + isExcludeVatAmount and omits its VAT counterpart line; the server derives the net/VAT split and generates the VAT line so the entry balances. When false (default), the caller must pre-split and pre-compute every line (current behaviour). Obtain valid VAT values from GET /core/latest/vat-cases and GET /core/v1/accounting/master-vats.",
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "confirmDontMindClosingFiscalYear",
"in": "query",
"description": "When true, accept the booking even if its bookingDate falls in a closing fiscal year. Defaults to false.",
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "ignore-unsubscripted-dates",
"in": "query",
"description": "When true, accept the booking even if its date falls outside the active Klara Accounting subscription period. Defaults to false.",
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "Accept-Language",
"in": "header",
"description": "Preferred language for any localized error messages produced downstream. Examples: de-CH, fr-CH, it-CH, en. Defaults to the tenant's configured language when omitted.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"requestBody": {
"description": "The booking to create, including its at-least-two balanced debit/credit lines.GET /core/v1/accounting/accounts → provides valid accountCode values (e.g. 1020, 1100, 2000, 3200). Only use this endpoint when you want to implement a seperate combobox with a flat master account list without sub-account context.GET /core/v1/accounting/accounts/account-displaying → provide full details about all valid, selectable accounts (combine name, combine code, master account, sub-account details when available). PREFERRED to use this endpoint as the booking line for some account code MUST include sub-account links if the sub-account exists.POST /core/latest/companies/{company-id}/documents → upload supporting documents (invoices, receipts, bank statements) and collect the returned documentId values to populate documentIds. This step should be done BEFORE invoking the booking creation. Important: when calling this endpoint for booking creation, always use category = LIABILITY_UPLOAD — no other category is permitted in this context (the documents are automatically moved to LIABILITIES when the booking is created successfully). The GUI for booking creation must always provide a document-upload step using the LIABILITY_UPLOAD category.GET /core/v1/accounting/booking-types → provides valid bookingTypeCode values (e.g. AR_PAYMENT, AP_INVOICE, GENERAL_LEDGER)GET /core/latest/vat-cases → provides VAT case IDs for the vat_case link keyGET /core/v1/accounting/master-vats → provides master VAT rate IDs for the vat_rate link keyGET /core/v1/accounting/vat-suggestions?direction=PURCHASE|SALE&amount=…&date=… → RECOMMENDED for VAT. Returns ready-to-use bundles; from the recommended row copy vatCaseLink and vatRateLink straight into the line's links (comma-joined) and vatAccountCode onto the line. Use with autoCalculateVat=true (see VAT auto-calculation below).GET /core/v1/accounting/vat-profile?date=… → the company VAT regime (effective vs net-tax-rate). Informational: it explains how the server will split the amount; you do not copy it into the booking.id (long) — Server-assigned. Set to 0 for new bookings.companyId (long) — Server-derived from token. Set to 0.bookingDate (string, yyyy-MM-ddT00:00:00Z, required) — Must fall in an open fiscal year.documentIds (array of string) — IDs of attached documents (gather from POST /core/latest/companies/{company-id}/documents with category = LIABILITY_UPLOAD). The documents are automatically moved to LIABILITIES on success booking creation. A GUI implementing booking creation must always provide a document-upload step — omitting it is only acceptable for purely internal adjustments where no document exists, in which case documentIds may be left empty ([]).internalComment (string) — Internal note visible only to accounting users.bookingStatus (string) — Allowed: DRAFT, BOOKED, CANCELLED.bookingDetails (array, required) — At least 2 balanced debit/credit lines (see below).expand (boolean) — UI hint. Use false.viewDocument (boolean) — UI hint. Use false.id (long) — Server-assigned. Set to 0.seq (int) — Line order starting at 0.accountCode (int, required) — From GET /core/v1/accounting/accounts or GET /core/v1/accounting/accounts/account-displaying (preferred; includes sub-account context when it exists).crdrType (string, required) — DR (debit) or CR (credit).description (string) — Free-text line description.amount (decimal, required) — Always positive. Total DR must equal total CR.tags (string, required) — Comma-separated list of string tags. Each tag should represent a topic that the booking line should be associated with, e.g. Operating Expenses. Tags are free-form and have no semantic meaning to Klara; they are simply stored and returned as-is. Provide at least one tag per line.links (string) — Comma-separated structured links. Two uses: (a) sub-account entities for the line's account code (from GET /core/v1/accounting/accounts/account-displaying); and (b) VAT links vat_case:… + vat_rate:… (from GET /core/v1/accounting/vat-suggestions) when this line carries VAT. Can be empty when neither applies.bookingTypeCode (string) — From GET /core/v1/accounting/booking-types.vatAccountCode (int) — Only with autoCalculateVat=true. The account the generated VAT line posts to (e.g. 1170); from the vatAccountCode of a vat-suggestions row.isExcludeVatAmount (boolean) — Only with autoCalculateVat=true. false = amount includes VAT (gross); true = amount excludes VAT (net base).isrReference (string) — ISR/QR-bill reference. Empty if not applicable.isrMember (string) — ISR participant number. Empty if not applicable.partnerIban (string) — Counterpart IBAN for payments. Empty if not applicable.vatBookingDetail (boolean) — Set to false for manual lines.autoCalculateVat=true) — book like the Manual booking GUI without doing VAT math:GET /core/v1/accounting/vat-suggestions?direction=PURCHASE|SALE&amount=<gross>&date=<bookingDate> and take the recommended row.links = \"<vatCaseLink>,<vatRateLink>\" (both values verbatim from that row), vatAccountCode = <row.vatAccountCode>, amount = <your gross or net>, and isExcludeVatAmount matching the amountKind you queried (false = gross).previewNet/previewVat). Provide only your account line(s) + the balancing line.vat-profile (effective → net + VAT line; net-tax-rate → flat-rate split; reverse-charge → an extra reverse VAT line). When autoCalculateVat is omitted/false you must instead pre-split and pre-compute every line yourself (see the \"Invoice received/sent\" examples).autoCalculateVat=true); amounts always positive; bookingDate in open fiscal year.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiBookingHeader"
},
"examples": {
"Money received": {
"description": "Customer pays an outstanding receivable via bank transfer (AR_PAYMENT). The bank line (1020) uses bank_account in links to identify the receiving bank sub-account.",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-06-15T00:00:00Z",
"documentIds": [],
"internalComment": "Customer payment for invoice INV-2024-001",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 1020,
"crdrType": "DR",
"description": "Receipt from customer A. Bassi AG",
"amount": 1080,
"tags": "sales,project-alpha",
"links": "bank_account:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/bank-accounts/85",
"bookingTypeCode": "GENERAL_LEDGER",
"partnerIban": "CH5604835012345678009",
"isrReference": "",
"isrMember": "",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 1100,
"crdrType": "CR",
"description": "Receipt from customer A. Bassi AG",
"amount": 1080,
"tags": "sales,project-alpha",
"links": "customer:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/customers/40",
"bookingTypeCode": "AR_PAYMENT",
"partnerIban": "",
"isrReference": "",
"isrMember": "",
"vatBookingDetail": false
}
]
}
},
"Money sent": {
"description": "Outgoing QR-bill payment to a supplier (AP_PAYMENT). Includes ISR reference, ISR member number and partner IBAN on the payable line (2000). The bank line (1020) uses bank_account in links.",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-06-15T00:00:00Z",
"documentIds": [],
"internalComment": "QR-bill payment to supplier — invoice SUP-2024-099",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 2000,
"crdrType": "DR",
"description": "Payment to supplier Müller GmbH",
"amount": 2500,
"tags": "supplier,office-supplies",
"links": "supplier:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/customers/37",
"bookingTypeCode": "AP_PAYMENT",
"partnerIban": "CH4431999123000889012",
"isrReference": "210000000003139471430009017",
"isrMember": "01-162-8",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 1020,
"crdrType": "CR",
"description": "Payment to supplier Müller GmbH",
"amount": 2500,
"tags": "supplier,office-supplies",
"links": "bank_account:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/bank-accounts/85",
"bookingTypeCode": "GENERAL_LEDGER",
"partnerIban": "",
"isrReference": "",
"isrMember": "",
"vatBookingDetail": false
}
]
}
},
"Invoice received": {
"description": "Supplier invoice posted with input-VAT split across 3 lines (AP_INVOICE). Material expense (4000) and VAT reclaim (1170) are debited; the full gross amount is credited to accounts payable (2000).",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-06-15T00:00:00Z",
"documentIds": [],
"internalComment": "Office supplies invoice from supplier — ref SUP-2024-099",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 4000,
"crdrType": "DR",
"description": "Office supplies — net amount",
"amount": 925.93,
"tags": "office-supplies,q2",
"links": "",
"bookingTypeCode": "GENERAL_LEDGER",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 1170,
"crdrType": "DR",
"description": "Office supplies — input VAT 8.1%",
"amount": 74.07,
"tags": "office-supplies,q2",
"links": "vat_case:/luz_accounting/api/vat-cases/1,vat_rate:/luz_accounting/api/master-vats/59",
"bookingTypeCode": "GENERAL_LEDGER",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": true
},
{
"id": 0,
"seq": 2,
"accountCode": 2000,
"crdrType": "CR",
"description": "Office supplies — total payable",
"amount": 1000,
"tags": "office-supplies,q2",
"links": "supplier:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/customers/37",
"bookingTypeCode": "AP_INVOICE",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
}
]
}
},
"Invoice sent": {
"description": "Customer invoice posted with output-VAT split across 3 lines (AR_INVOICE). The full gross amount is debited to accounts receivable (1100); Revenue from deliveries and services (3000) and output VAT (2200) are credited.",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-06-15T00:00:00Z",
"documentIds": [],
"internalComment": "Consulting services invoice to customer A. Bassi AG — ref INV-2024-001",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 1100,
"crdrType": "DR",
"description": "Consulting services — total receivable",
"amount": 1081,
"tags": "consulting,project-alpha",
"links": "customer:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/customers/40",
"bookingTypeCode": "AR_INVOICE",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 3000,
"crdrType": "CR",
"description": "Consulting services — net revenue",
"amount": 1000,
"tags": "consulting,project-alpha",
"links": "",
"bookingTypeCode": "GENERAL_LEDGER",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 2,
"accountCode": 2200,
"crdrType": "CR",
"description": "Consulting services — output VAT 8.1%",
"amount": 81,
"tags": "consulting,project-alpha",
"links": "vat_case:/luz_accounting/api/vat-cases/1,vat_rate:/luz_accounting/api/master-vats/58",
"bookingTypeCode": "GENERAL_LEDGER",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": true
}
]
}
},
"General ledger": {
"description": "Simple two-line accrual entry where all lines use GENERAL_LEDGER. Suitable for adjustments that do not involve AR, AP, or tax sub-ledgers.",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-06-15T00:00:00Z",
"documentIds": [],
"internalComment": "Monthly accrual — prepaid insurance June 2024",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 1300,
"crdrType": "DR",
"description": "Prepaid insurance — June 2024",
"amount": 1200,
"tags": "insurance,accrual",
"links": "",
"bookingTypeCode": "GENERAL_LEDGER",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 6000,
"crdrType": "CR",
"description": "Prepaid insurance — June 2024",
"amount": 1200,
"tags": "insurance,accrual",
"links": "",
"bookingTypeCode": "GENERAL_LEDGER",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
}
]
}
},
"Manual booking": {
"description": "Maximum-flexibility entry demonstrating all optional fields at once: bank sub-account (bank_account link), ISR reference, ISR member, partner IBAN, service period dates, and a pre-uploaded document attachment.",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-06-15T00:00:00Z",
"documentDate": "2024-06-10",
"documentIds": [
"98765"
],
"internalComment": "Manual correction — shows all optional fields",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 1020,
"crdrType": "DR",
"description": "Manual entry — bank side",
"amount": 500,
"tags": "manual,correction",
"links": "bank_account:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/bank-accounts/85",
"bookingTypeCode": "GENERAL_LEDGER",
"partnerIban": "CH5604835012345678009",
"isrReference": "210000000003139471430009017",
"isrMember": "01-162-8",
"servicePeriodFrom": "2024-06-01T00:00:00Z",
"servicePeriodTo": "2024-06-30T00:00:00Z",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 3000,
"crdrType": "CR",
"description": "Manual entry — revenue side",
"amount": 500,
"tags": "manual,correction",
"links": "",
"bookingTypeCode": "GENERAL_LEDGER",
"partnerIban": "",
"isrReference": "",
"isrMember": "",
"vatBookingDetail": false
}
]
}
},
"Post depreciation": {
"description": "Year-end straight-line asset depreciation (AMORTIZATION). Depreciation expense (6800) is debited; the accumulated-depreciation contra-asset account (1509) is credited with bookingTypeCode AMORTIZATION.",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-12-31T00:00:00Z",
"documentIds": [],
"internalComment": "Annual depreciation — office equipment 2024",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 6800,
"crdrType": "DR",
"description": "Depreciation expense — office equipment 2024",
"amount": 3000,
"tags": "depreciation,fixed-assets",
"links": "financial_asset:/luz_accounting/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/financial-asset/17",
"bookingTypeCode": "GENERAL_LEDGER",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 1509,
"crdrType": "CR",
"description": "Accumulated depreciation — office equipment 2024",
"amount": 3000,
"tags": "depreciation,fixed-assets",
"links": "",
"bookingTypeCode": "AMORTIZATION",
"isrReference": "",
"isrMember": "",
"partnerIban": "",
"vatBookingDetail": false
}
]
}
},
"VAT auto-calculation (autoCalculateVat=true)": {
"description": "Send with query param autoCalculateVat=true. The expense line (4000) carries the gross amount + vat_case/vat_rate links + vatAccountCode and OMITS the VAT line; the server splits it (925.93 net + 74.07 VAT to 1170) and balances against the payable (2000). Get the link values from GET /core/v1/accounting/vat-suggestions.",
"value": {
"id": 0,
"companyId": 0,
"bookingDate": "2024-06-15T00:00:00Z",
"documentIds": [],
"internalComment": "Office supplies — VAT auto-calculated by the server",
"bookingStatus": "BOOKED",
"expand": false,
"viewDocument": false,
"bookingDetails": [
{
"id": 0,
"seq": 0,
"accountCode": 4000,
"crdrType": "DR",
"description": "Office supplies — gross amount (VAT included)",
"amount": 1000,
"isExcludeVatAmount": false,
"links": "vat_case:/luz_accounting/api/vat-cases/1,vat_rate:/luz_accounting/api/master-vats/59",
"vatAccountCode": 1170,
"bookingTypeCode": "GENERAL_LEDGER",
"tags": "office-supplies",
"vatBookingDetail": false
},
{
"id": 0,
"seq": 1,
"accountCode": 2000,
"crdrType": "CR",
"description": "Total payable (gross)",
"amount": 1000,
"links": "",
"bookingTypeCode": "AP_INVOICE",
"tags": "office-supplies",
"vatBookingDetail": false
}
]
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Booking created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiBookingHeader"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/bookings/{id}/documents": {
"put": {
"tags": [
"Accounting"
],
"summary": "Replace the document attachments and document date of an existing booking.",
"description": "Replaces the set of supporting-document identifiers and the document date stored on an existing accounting booking. The operation is a full replacement — pass an empty documentIds array to clear all existing attachments, or omit documentDate / set it to null to clear it. By default the operation fails when the booking's existing bookingDate falls outside the active Klara Accounting subscription window; set ignore-unsubscripted-dates to true to bypass this guard. Tenant and company are derived from the bearer token — the booking {id} must belong to the caller's company. The caller must hold the ACCOUNTING permission on that company. The endpoint is idempotent: re-sending the same body produces the same state. Returns HTTP 200 with no body on success.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Internal id of the booking whose documents should be replaced. Obtain from the id field returned by POST /core/v1/bookings.",
"required": true,
"schema": {
"format": "int64",
"type": "integer",
"example": 12345
},
"example": 12345
},
{
"name": "ignore-unsubscripted-dates",
"in": "query",
"description": "When true, accept the update even if the booking's bookingDate falls outside the active Klara Accounting subscription period. Defaults to false.",
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
}
],
"requestBody": {
"description": "Document metadata to apply to the booking. The operation is a full replacement of both documentDate and documentIds.POST /core/v1/bookings → provides the booking id used in the URL.POST /core/latest/companies/{company-id}/documents → upload the file first and use the returned documentId as an entry in documentIds. Each entry is either a numeric Klara document id (e.g. \"98765\") or a Klara document URI.documentDate (string, ISO date yyyy-MM-dd, optional) — date printed on the underlying paper document. Set to null or omit to clear the existing value.documentIds (array of string, optional, max 50 entries, each ≤ 512 chars) — full replacement of the attached document references. Send [] to clear.documentIds clears all existing attachments on the booking.bookingDate must fall in an active Klara Accounting subscription window; use ignore-unsubscripted-dates=true to bypass.type. The caller must hold the FINANCE_BANK_ACCOUNT permission on the target company. The result is sorted by Swiss-bank name then IBAN. This operation is idempotent and read-only — it can be safely retried.",
"parameters": [
{
"name": "iban-number",
"in": "query",
"description": "Optional IBAN filter. When provided, the response contains the single matching bank account (returned as a one-element array for a uniform response shape) or HTTP 404 if no account exists with that IBAN. Spaces in the IBAN are tolerated. When provided, the type parameter is ignored.",
"required": false,
"schema": {
"type": "string",
"example": "CH7109000000252946932"
},
"example": "CH7109000000252946932"
},
{
"name": "type",
"in": "query",
"description": "Optional business-type filter. Allowed values: AR (Accounts Receivable), AP (Accounts Payable), HR (Salary / HR payments). When omitted, all bank accounts are returned. Ignored when iban-number is provided.",
"required": false,
"schema": {
"enum": [
"AR",
"AP",
"HR"
],
"type": "string",
"example": "AR"
},
"example": "AR"
}
],
"responses": {
"200": {
"description": "Bank accounts of the authenticated company.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanyBankAccount"
}
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/customers": {
"get": {
"tags": [
"Customer"
],
"summary": "Search and page the customers of the caller's company.",
"description": "Returns a page of customers (Persons + Companies) of the caller's company, with optional free-text search (search-key) and status filter (status). Results are paged with offset and limit: to retrieve every customer, iterate offset=0, limit, 2×limit, … until a response returns fewer than limit rows. All query parameters are optional; without any, the endpoint returns the first 50 active customers (downstream default ordering). This is a read-only, idempotent operation. @CurrentSession Token) and are never accepted as parameters. The caller must be authenticated (apiKeyAuth + bearerAuth) and must hold the FINANCE_GET_CUSTOMER permission on that company; otherwise the endpoint returns 403.",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.",
"schema": {
"default": "50",
"maximum": 100,
"minimum": 1,
"type": "integer",
"example": 50
}
},
{
"name": "offset",
"in": "query",
"description": "0-based pagination offset — the number of customers to skip before the returned page. Defaults to 0. Combine with limit to walk the full list.",
"schema": {
"default": "0",
"minimum": 0,
"type": "integer",
"example": 0
}
},
{
"name": "search-key",
"in": "query",
"description": "Free-text search across customer name, email, phone and customer number. Tokenised on whitespace; matches are case-insensitive substring matches. Maximum length 256 characters.",
"schema": {
"maxLength": 256,
"type": "string",
"example": "müller"
}
},
{
"name": "status",
"in": "query",
"description": "Filter by customer state. Allowed values: ACTIVE, ALL, ARCHIVED. When omitted, the downstream service applies its default (active customers only).",
"schema": {
"maxLength": 16,
"enum": [
"ACTIVE",
"ALL",
"ARCHIVED"
],
"type": "string",
"example": "ACTIVE"
}
}
],
"responses": {
"200": {
"description": "Customers",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Customer"
}
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/employees/short-info": {
"get": {
"tags": [
"Payroll"
],
"summary": "List the company's employees as short-info entries, filtered and sorted.",
"description": "Returns a lightweight directory of the authenticated company's employees (id, name, email, employee number, workplace, status), resolved from the compensation and person records. Each entry's id is the employeeId consumed by other employee-scoped endpoints (e.g. GET /payroll/employees/{employeeId}/addable-salary-items) — call this endpoint first to resolve an employee's id. Results can be narrowed with a free-text search-key (matched against name, employee number and email), restricted to specific workplaces via workplace-ids, and filtered by contract filter-by-status; ordering is controlled by sort-field and sort-direction. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION_TIME_TRACKING permission on that company.",
"parameters": [
{
"name": "filter-by-status",
"in": "query",
"description": "Contract-status filter. Allowed values: ALL, ACTIVE, INACTIVE, DRAFT. Defaults to ALL.",
"required": false,
"schema": {
"description": "Contract-status filter. Allowed values: ALL, ACTIVE, INACTIVE, DRAFT. Defaults to ALL.",
"default": "ALL",
"enum": [
"ALL",
"ACTIVE",
"INACTIVE",
"DRAFT"
],
"type": "string",
"example": "ALL"
},
"example": "ALL"
},
{
"name": "search-key",
"in": "query",
"description": "Case-insensitive substring matched against the employee's full name, employee number and email. When omitted, no text filter is applied.",
"required": false,
"schema": {
"maxLength": 256,
"type": "string"
}
},
{
"name": "sort-direction",
"in": "query",
"description": "Sort direction. Allowed values: ASC, DESC.",
"required": false,
"schema": {
"$ref": "#/components/schemas/SortDirection"
}
},
{
"name": "sort-field",
"in": "query",
"description": "Field to sort by. Allowed values: NAME, EMAIL, EMPLOYEE_NUMBER. Defaults to NAME.",
"required": false,
"schema": {
"description": "Field to sort the employee listing by. Allowed values: NAME, EMAIL, EMPLOYEE_NUMBER.",
"default": "NAME",
"enum": [
"NAME",
"EMAIL",
"EMPLOYEE_NUMBER"
],
"type": "string",
"example": "NAME"
},
"example": "NAME"
},
{
"name": "workplace-ids",
"in": "query",
"description": "Restrict results to employees whose current contract workplace is in this set. Repeat the parameter for multiple ids (e.g. workplace-ids=12&workplace-ids=13). When omitted, employees of all workplaces are returned.",
"required": false,
"schema": {
"type": "array",
"items": {
"format": "int64",
"type": "integer"
}
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiEmployeeShortInfo"
}
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/invoices": {
"put": {
"tags": [
"Finance"
],
"summary": "Update an existing DRAFT invoice for the authenticated company.",
"description": "Updates a DRAFT invoice identified by invoice.id in the request body. Only invoices in DRAFT status can be updated — any other status returns 400. If the incoming status is INVOICED or SENT, the invoice is booked into KLARA accounting and inventory transactions are created, identical to the booking behavior of POST /core/v1/invoices. This is the call that finalizes a DRAFT — the GUI equivalent of posting in the final step; status is caller-controlled, so keep it DRAFT to re-save without booking. This endpoint does not send/deliver the invoice (no email/ePost/eBill/print&send), regardless of postMethod; retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself. The caller must hold the FINANCE permission on the target company.status=INVOICED/SENT here creates the accounting booking but renders/stores no PDF. To attach the printed invoice to the booking, after this call run (1) POST /core/v1/invoices/{id}/printed-document to render and store the printedFileId, then (2) PUT /core/v1/bookings/{id}/documents to link that printedFileId (in documentIds) to the booking from bookingNumbers.",
"parameters": [
{
"name": "confirmDontMindClosingFiscalYear",
"in": "query",
"description": "When true, allows save/booking even if the document date falls inside a closing or closed fiscal year. Defaults to false.",
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
}
],
"requestBody": {
"description": "Updates an existing DRAFT invoice. The body structure is identical to POST /core/v1/invoices with one critical difference: id must be the numeric primary key of an existing invoice currently in DRAFT status.POST /core/v1/invoices with status=DRAFT to create the invoice.GET /core/v1/invoices/{id} to retrieve the current state.status to INVOICED/SENT.GET /core/v1/invoices/{id} → provides the current invoice body to modify and re-submit.GET /core/v1/company-bank-accounts → provides updated ibanNumberCHF / ibanNumberCHW.GET /core/latest/articles/search?keyword=... → search for articles to add/change order items.GET /core/v1/bank-reconciliation/open-positions → provides openPositionsLinkedToInvoice[] for reconciliation.GET /core/latest/company-configuration/including-vat → provides usingVAT default.id (long, required) — must be > 0 and match an existing DRAFT invoice. Returns 400 if the stored invoice is not in DRAFT status.invoiceCode — uniqueness is NOT re-validated; retain the original value.order.id — must match the existing order; retain from the original invoice.status — set to INVOICED or SENT to book the invoice (triggers accounting); set to DRAFT to save without booking.id (long, required) — must be > 0 (existing DRAFT invoice id).invoiceCode (String, required) — must not be empty; retain the original value.orderType (String, required) — must be INVOICE.status (String, required) — DRAFT (saves without booking), INVOICED (saves and books into accounting), SENT (saves and books; does not send/deliver the invoice).postMethod (String, optional) — distribution channel recorded on the invoice only; not delivered. Allowed: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.documentDate (date, required) — invoice issue date, format yyyy-MM-dd; must fall inside the active subscription period.paymentDate (date, required when amount > 0) — must be on or after documentDate.ibanNumberCHF (String, conditional) — CHF IBAN; format validated when provided.ibanNumberCHW (String, optional) — WIR IBAN; format validated when provided.wirAcceptanceRate (int, optional) — WIR acceptance percentage (0–100).amount (BigDecimal, required) — total invoice amount. Caller-supplied; not recomputed by the server.usingVAT (boolean) — GUI checkbox \"VAT included in amount of each item\": item price/amount are VAT-inclusive (true, gross) or VAT-exclusive (false, net). It does not switch VAT on/off. Same VAT-handling rules as POST /core/v1/invoices (server stores amounts verbatim).usingExportVat (boolean, optional) — GUI checkbox \"Export\"; when true set every orderItems[].vat.rate to 0. Defaults to false.subject, ourReference, yourReference, companyCityAndDate, closeAndSignature — optional text fields.order (required):order.id (long) — must be the existing order id; retain from the original invoice.order.orderNumber (int) — retain from the original invoice.order.companyId (long) — must match the authenticated company; set from bearer token on the downstream.order.customer (object, required) — existing customer; retain from original invoice.orderItems[] (required, at least 1):POST /core/v1/invoices. Existing item ids (> 0) update items in-place; id = 0 adds new items.orderItems[].tag (String, required when booking) — must not be empty when status is INVOICED/SENT.attachments[] and openPositionsLinkedToInvoice[]:POST /core/v1/invoices.id must be > 0 (adapter guard) and the stored invoice must be DRAFT (downstream guard).paymentDate must be on or after documentDate when amount > 0.orderItems[].tag must be present when status triggers booking (INVOICED/SENT).documentDate.vatDate, lastModified, createDate, bookingDueDate, bookingNumbers, businessCaseId, bookingStatus, bookingMessage, bookingSealed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invoice"
},
"examples": {
"Update DRAFT to INVOICED": {
"summary": "Book an existing DRAFT invoice by changing status to INVOICED",
"value": {
"id": 42,
"invoiceCode": "123457736",
"paymentDate": "2026-06-28",
"ibanNumberCHF": "CH7109000000252946932",
"wirAcceptanceRate": 0,
"invoiceType": "MANUAL",
"order": {
"id": 55,
"orderNumber": 377,
"orderName": "Updated invoice",
"customer": {
"id": 40,
"company": {
"id": 34,
"name": "A. Bassi AG",
"emails": [
{
"id": "35",
"emailAddress": "chris.sutter@klara.ch",
"type": "PRIVATE"
}
],
"addresses": [
{
"id": 280,
"companyName": "A. Bassi AG",
"type": "COMPANY",
"addressType": "WORK",
"street": "Ahornstrasse",
"homeNumber": "12",
"city": {
"id": 3713,
"addressPostcode": "8962",
"cityName18": "Bergdietikon"
}
}
],
"language": "de"
},
"customerType": "COMPANY",
"termsOfPayment": 30
},
"companyId": 1
},
"status": "INVOICED",
"amount": 500,
"orderItems": [
{
"position": 1,
"itemNumer": "P0000061123",
"description": "Mobile Prepayment",
"quantity": 1,
"unit": "Unit",
"price": 500,
"discount": 0,
"vat": {
"vatCode": "1",
"rate": 5.3,
"description": "Reduced VAT rate",
"masterId": 42
},
"amount": 500,
"tag": "prepayment",
"vatCase": "TAXABLE_SUPPLY",
"articleType": "PREPAYMENT",
"id": 0
}
],
"attachments": [],
"openPositionsLinkedToInvoice": [],
"subject": "Updated invoice",
"usingVAT": true,
"orderType": "INVOICE",
"documentDate": "2026-05-29",
"postMethod": "PRINT_AND_MANUAL_SEND"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Invoice updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invoice"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Finance"
],
"summary": "Create a new KLARA invoice for the authenticated company.",
"description": "Creates a new invoice for an existing customer under the company resolved from the bearer JWT. The request body's id must be 0 or omitted — this endpoint does not support updating existing invoices.GET /core/v1/invoices/next-invoice-number to obtain the next invoice number.GET /core/latest/customers (with search filters).GET /core/v1/company-bank-accounts.GET /core/latest/articles/search or GET /core/latest/articles/article-numbers to populate order items.GET /core/v1/bank-reconciliation/open-positions to reconcile prepayments / credit notes.POST /core/v1/orders/next-order-number to obtain the next order.orderNumber.GET /core/latest/company-configuration/including-vat to determine the company default for usingVAT.status=INVOICED to save and book, or status=DRAFT to save without booking.INVOICED or SENT the invoice is also booked into KLARA accounting, inventory transactions are created and the HubSpot indicator is synchronised. This endpoint does not send/deliver the invoice (no email/ePost/eBill/print&send), regardless of postMethod or a SENT status; retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself. The caller must hold the FINANCE permission on the target company.DRAFT until the user posts it in the final step; via the API you choose — send status=DRAFT to save without booking, or status=INVOICED (or SENT) to book immediately. A DRAFT can be finalized later with PUT /core/v1/invoices (status=INVOICED).status=INVOICED/SENT), the accounting booking is created but no PDF is rendered or stored — the invoice and its booking have no printed document (unlike the GUI, which renders, stores and books in one step). To attach the printed invoice, run two follow-up calls: (1) POST /core/v1/invoices/{id}/printed-document to render the PDF and store its printedFileId on the invoice, then (2) PUT /core/v1/bookings/{id}/documents to link that printedFileId (in documentIds) to the booking returned in bookingNumbers.",
"parameters": [
{
"name": "confirmDontMindClosingFiscalYear",
"in": "query",
"description": "When true, allows save/booking even if the document date falls inside a closing or closed fiscal year. Defaults to false.",
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "Accept-Language",
"in": "header",
"description": "Preferred response language as a BCP-47 tag (e.g. en, de, fr, it). Forwarded to luzfin_finance.",
"schema": {
"type": "string",
"example": "en"
},
"example": "en"
}
],
"requestBody": {
"description": "Creates a new invoice for an existing customer. The id field must be 0 or omitted. This endpoint does not support updating existing invoices.GET /core/v1/invoices/next-invoice-number → provides invoiceCode and invoiceNumber (the next available invoice number for the company).GET /core/latest/customers?searchKey=...&limit=... → provides order.customer.id, order.customer.company (with addresses, emails), and order.customer.customerType.GET /core/v1/company-bank-accounts → provides ibanNumberCHF / ibanNumberCHW for payment accounts.GET /core/latest/articles/search?keyword=... → search articles by keyword for the autocomplete; provides orderItems[].itemNumer, description, price, vat, unit.GET /core/latest/articles/article-numbers?article-numbers=... → fetch full article data by article number(s) to fill orderItems[].GET /core/latest/articles/{article-id}/article-set-items → expands article set/bundle into component line items for orderItems[].GET /core/v1/bank-reconciliation/open-positions → lists customer's open prepayments / credit notes that can be reconciled; provides openPositionsLinkedToInvoice[].bookingTypeCode, bookingDetailUri, partialPaymentAmount.POST /core/v1/orders/next-order-number → provides order.orderNumber; each call advances the in-memory counter — call immediately before creating the invoice, not speculatively.GET /core/latest/company-configuration/including-vat → provides the company-level default for usingVAT; returns false when no configuration record exists.printedFileId (String, server-assigned) — populated automatically by POST /core/v1/invoices/{id}/printed-document after PDF generation; omit on creation.id (long, required) — must be 0 for creation.invoiceCode (String, required) — unique invoice code; obtain from GET /core/v1/invoices/next-invoice-number.orderType (String, required) — must be INVOICE.status (String, required) — determines booking behavior (not delivery). Allowed: DRAFT (saves without booking), INVOICED (saves and books into accounting), SENT (saves and books; does not send/deliver the invoice).postMethod (String, optional) — distribution channel recorded on the invoice only; this endpoint does not deliver the invoice. Allowed: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.documentDate (date, required) — invoice issue date, format yyyy-MM-dd.paymentDate (date, required) — payment due date, must be on or after documentDate.ibanNumberCHF (String, conditional) — CHF IBAN for payment; required when booking is triggered.ibanNumberCHW (String, optional) — WIR IBAN for combined payments.wirAcceptanceRate (int, optional) — WIR acceptance percentage (0–100).invoiceType (String, required) — MANUAL or RECURRING.amount (BigDecimal, required) — total invoice amount over all items. Caller-supplied; not recomputed by the server. With usingVAT=false this is net + VAT; with usingVAT=true it is the sum of the gross item amounts.usingVAT (boolean) — GUI checkbox \"VAT included in amount of each item\". Controls whether item price/amount are VAT-inclusive (true, gross) or VAT-exclusive (false, net). It does not switch VAT on/off (that is the company's VAT registration). Use GET /core/latest/company-configuration/including-vat for the company default. See VAT handling below.usingExportVat (boolean, optional) — GUI checkbox \"Export\". When true, the invoice is an export: set every orderItems[].vat.rate to 0 so no VAT is charged. Defaults to false.subject (String, optional) — invoice subject/title.ourReference / yourReference (String, optional) — reference texts.companyCityAndDate (String, optional) — city and date line printed on invoice.closeAndSignature (String, optional) — closing text and signature block.printedFileId (String, optional) — document ID of uploaded PDF from partner system.order (required):order.id (long) — must be 0 for new orders.order.orderNumber (int, required) — unique order number; must be > 0 (validated). Obtain from POST /core/v1/orders/next-order-number (not idempotent — each call advances the counter).order.orderName (String, optional) — order description.order.companyId (long, required) — company ID from bearer token scope.order.customer (object, required) — existing customer; obtain from GET /core/v1/customers. Must include customer.id, customer.company (with addresses), and customer.customerType (COMPANY or PERSON).orderItems[] (required, at least 1):orderItems[].position (int) — line item position (1-based).orderItems[].itemNumer (String) — article number.orderItems[].description (String) — item description.orderItems[].quantity (double) — quantity.orderItems[].unit (String) — unit of measure (e.g. Unit, Hour).orderItems[].price (double) — unit price (negative for credit notes). VAT-inclusive (gross) when usingVAT=true, VAT-exclusive (net) when usingVAT=false. Both variants are available from the article lookup APIs.orderItems[].discount (double) — discount percentage.orderItems[].amount (double) — line total = quantity × price × (1 − discount/100), rounded to the nearest 0.05. Gross or net following usingVAT (same basis as price).orderItems[].tag (String, required for booking) — tags field; must not be empty when status is INVOICED/SENT.orderItems[].vatCase (String) — TAXABLE_SUPPLY, EXEMPT_SUPPLY, REVERSE_CHARGE.orderItems[].articleType (String) — PRODUCTION, PREPAYMENT, SERVICE.orderItems[].vat (object) — VAT details: vatCode, rate, description, masterId. For an export invoice (usingExportVat=true) set rate=0 and the export/zero vatCode.orderItems[].id (long) — must be 0 for new items.orderItems[].price, orderItems[].amount, orderItems[].vat and the document amount already consistent with the two flags:usingVAT=false (VAT-exclusive) — price/amount are net; document amount = net + VAT.usingVAT=true (VAT-inclusive) — price/amount are gross (VAT already inside); document amount = sum of gross item amounts.usingExportVat=true (export) — set every orderItems[].vat.rate to 0; VAT = 0 and document amount = sum of net item amounts.amount = round0.05(quantity × price × (1 − discount/100)); VAT per rate group = amount × rate/100 when VAT-exclusive, or amount × (rate/100) / (1 + rate/100) when VAT-inclusive — each rounded to the nearest 0.05 (Swiss commercial rounding). Article unit prices for the inclusive, exclusive and export cases come from the article lookup APIs above (each article exposes both a VAT-inclusive and a VAT-exclusive price); pick the one matching usingVAT/usingExportVat.attachments[] (optional):attachments[].fileId (String) — document file ID uploaded via partner system.attachments[].orderDetailId (long) — set to 0 for new invoices.attachments[].id (long) — set to 0 for new attachments.openPositionsLinkedToInvoice[] (optional, for reconciliation):openPositionsLinkedToInvoice[].bookingTypeCode (String) — AR_PREPAYMENT or AR_CREDITNOTE.openPositionsLinkedToInvoice[].bookingDetailUri (String) — internal URI of the booking detail to reconcile (format: /luz_accounting/api/{tenant-id}/companies/{companyId}/bookings/{bookingId}/booking-details/{detailId}).openPositionsLinkedToInvoice[].partialPaymentAmount (BigDecimal) — amount to offset from this open position.paymentDate must be on or after documentDate (when amount > 0).order.orderNumber must be > 0.invoiceCode must be unique within the company.status must not be null.SENT, credit notes (negative total) are not allowed.orderItems[].tag must be present when status triggers booking (INVOICED/SENT).vatDate, lastModified, createDate, bookingDueDate, bookingNumbers, businessCaseId, bookingStatus, bookingMessage, bookingSealed, fiscalYearHasCreatedAuto, createBy, issuedDate.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invoice"
},
"examples": {
"With articles only": {
"summary": "Create invoice with a list of items (articles)",
"value": {
"invoiceCode": "123457736",
"paymentDate": "2026-06-28",
"ibanNumberCHF": "CH7109000000252946932",
"wirAcceptanceRate": 0,
"invoiceType": "MANUAL",
"id": 0,
"order": {
"id": 0,
"orderNumber": 377,
"orderName": "Test create invoice",
"customer": {
"id": 40,
"company": {
"id": 34,
"name": "A. Bassi AG",
"emails": [
{
"id": "35",
"emailAddress": "chris.sutter@klara.ch",
"type": "PRIVATE"
}
],
"addresses": [
{
"id": 280,
"companyName": "A. Bassi AG",
"type": "COMPANY",
"addressType": "WORK",
"street": "Ahornstrasse",
"homeNumber": "12",
"city": {
"id": 3713,
"addressPostcode": "8962",
"cityName18": "Bergdietikon"
}
}
],
"language": "de"
},
"customerType": "COMPANY",
"termsOfPayment": 30
},
"companyId": 1
},
"status": "INVOICED",
"amount": 500,
"orderItems": [
{
"position": 1,
"itemNumer": "P0000061123",
"description": "Mobile Prepayment",
"quantity": 1,
"unit": "Unit",
"price": 500,
"discount": 0,
"vat": {
"vatCode": "1",
"rate": 5.3,
"description": "Reduced VAT rate",
"masterId": 42
},
"amount": 500,
"tag": "prepayment",
"vatCase": "TAXABLE_SUPPLY",
"articleType": "PREPAYMENT",
"id": 0
}
],
"attachments": [],
"openPositionsLinkedToInvoice": [],
"subject": "Test create invoice",
"usingVAT": true,
"orderType": "INVOICE",
"documentDate": "2026-05-29",
"postMethod": "PRINT_AND_MANUAL_SEND"
}
},
"With articles and attachment": {
"summary": "Create invoice with items and a document attachment",
"value": {
"invoiceCode": "123457737",
"paymentDate": "2026-06-28",
"ibanNumberCHF": "CH7109000000252946932",
"wirAcceptanceRate": 0,
"invoiceType": "MANUAL",
"id": 0,
"order": {
"id": 0,
"orderNumber": 378,
"orderName": "Invoice with attachment",
"customer": {
"id": 40,
"company": {
"id": 34,
"name": "A. Bassi AG",
"emails": [
{
"id": "35",
"emailAddress": "chris.sutter@klara.ch",
"type": "PRIVATE"
}
],
"addresses": [
{
"id": 280,
"companyName": "A. Bassi AG",
"type": "COMPANY",
"addressType": "WORK",
"street": "Ahornstrasse",
"homeNumber": "12",
"city": {
"id": 3713,
"addressPostcode": "8962",
"cityName18": "Bergdietikon"
}
}
],
"language": "de"
},
"customerType": "COMPANY",
"termsOfPayment": 30
},
"companyId": 1
},
"status": "INVOICED",
"amount": 500,
"orderItems": [
{
"position": 1,
"itemNumer": "P0000061123",
"description": "Mobile Prepayment",
"quantity": 1,
"unit": "Unit",
"price": 500,
"discount": 0,
"vat": {
"vatCode": "1",
"rate": 5.3,
"description": "Reduced VAT rate",
"masterId": 42
},
"amount": 500,
"tag": "prepayment",
"vatCase": "TAXABLE_SUPPLY",
"articleType": "PREPAYMENT",
"id": 0
}
],
"attachments": [
{
"orderDetailId": 0,
"fileId": "1771764",
"id": 0
}
],
"openPositionsLinkedToInvoice": [],
"subject": "Invoice with attachment",
"usingVAT": true,
"orderType": "INVOICE",
"documentDate": "2026-05-29",
"postMethod": "PRINT_AND_MANUAL_SEND"
}
},
"With articles and reconciliation": {
"summary": "Create invoice with items and prepayment reconciliation",
"value": {
"invoiceCode": "123457738",
"paymentDate": "2026-06-28",
"ibanNumberCHF": "CH7109000000252946932",
"wirAcceptanceRate": 0,
"invoiceType": "MANUAL",
"id": 0,
"order": {
"id": 0,
"orderNumber": 383,
"orderName": "Invoice with reconciliation",
"customer": {
"id": 40,
"company": {
"id": 34,
"name": "A. Bassi AG",
"emails": [
{
"id": "35",
"emailAddress": "chris.sutter@klara.ch",
"type": "PRIVATE"
}
],
"addresses": [
{
"id": 280,
"companyName": "A. Bassi AG",
"type": "COMPANY",
"addressType": "WORK",
"street": "Ahornstrasse",
"homeNumber": "12",
"city": {
"id": 3713,
"addressPostcode": "8962",
"cityName18": "Bergdietikon"
}
}
],
"language": "de"
},
"customerType": "COMPANY",
"termsOfPayment": 30
},
"companyId": 1
},
"status": "INVOICED",
"amount": 1500,
"orderItems": [
{
"position": 1,
"itemNumer": "P0000061123",
"description": "Mobile Prepayment",
"quantity": 5,
"unit": "Unit",
"price": 500,
"discount": 0,
"vat": {
"vatCode": "1",
"rate": 5.3,
"description": "Reduced VAT rate",
"masterId": 42
},
"amount": 2500,
"tag": "prepayment",
"vatCase": "TAXABLE_SUPPLY",
"articleType": "PREPAYMENT",
"id": 0
},
{
"position": 2,
"itemNumer": "P0000061142",
"description": "Credit note",
"quantity": 1,
"unit": "Unit",
"price": -1000,
"discount": 0,
"vat": {
"vatCode": "1",
"rate": 5.3,
"description": "Reduced VAT rate",
"masterId": 42
},
"amount": -1000,
"tag": "tag",
"vatCase": "TAXABLE_SUPPLY",
"articleType": "PRODUCTION",
"id": 0
}
],
"attachments": [],
"openPositionsLinkedToInvoice": [
{
"bookingTypeCode": "AR_PREPAYMENT",
"bookingDetailUri": "/luz_accounting/api/{tenant-id}/companies/1/bookings/1982/booking-details/11298",
"partialPaymentAmount": 500
},
{
"bookingTypeCode": "AR_PREPAYMENT",
"bookingDetailUri": "/luz_accounting/api/{tenant-id}/companies/1/bookings/1983/booking-details/11302",
"partialPaymentAmount": 500
}
],
"subject": "Invoice with reconciliation",
"usingVAT": true,
"orderType": "INVOICE",
"documentDate": "2026-05-29",
"postMethod": "PRINT_AND_MANUAL_SEND"
}
},
"With articles, attachment and reconciliation": {
"summary": "Create invoice with items, attachment and prepayment reconciliation",
"value": {
"invoiceCode": "123457739",
"paymentDate": "2026-06-28",
"ibanNumberCHF": "CH7109000000252946932",
"wirAcceptanceRate": 0,
"invoiceType": "MANUAL",
"id": 0,
"order": {
"id": 0,
"orderNumber": 384,
"orderName": "Invoice with attachment and reconciliation",
"customer": {
"id": 40,
"company": {
"id": 34,
"name": "A. Bassi AG",
"emails": [
{
"id": "35",
"emailAddress": "chris.sutter@klara.ch",
"type": "PRIVATE"
}
],
"addresses": [
{
"id": 280,
"companyName": "A. Bassi AG",
"type": "COMPANY",
"addressType": "WORK",
"street": "Ahornstrasse",
"homeNumber": "12",
"city": {
"id": 3713,
"addressPostcode": "8962",
"cityName18": "Bergdietikon"
}
}
],
"language": "de"
},
"customerType": "COMPANY",
"termsOfPayment": 30
},
"companyId": 1
},
"status": "INVOICED",
"amount": 1500,
"orderItems": [
{
"position": 1,
"itemNumer": "P0000061123",
"description": "Mobile Prepayment",
"quantity": 5,
"unit": "Unit",
"price": 500,
"discount": 0,
"vat": {
"vatCode": "1",
"rate": 5.3,
"description": "Reduced VAT rate",
"masterId": 42
},
"amount": 2500,
"tag": "prepayment",
"vatCase": "TAXABLE_SUPPLY",
"articleType": "PREPAYMENT",
"id": 0
},
{
"position": 2,
"itemNumer": "P0000061142",
"description": "Credit note",
"quantity": 1,
"unit": "Unit",
"price": -1000,
"discount": 0,
"vat": {
"vatCode": "1",
"rate": 5.3,
"description": "Reduced VAT rate",
"masterId": 42
},
"amount": -1000,
"tag": "tag",
"vatCase": "TAXABLE_SUPPLY",
"articleType": "PRODUCTION",
"id": 0
}
],
"attachments": [
{
"orderDetailId": 0,
"fileId": "1771764",
"id": 0
}
],
"openPositionsLinkedToInvoice": [
{
"bookingTypeCode": "AR_PREPAYMENT",
"bookingDetailUri": "/luz_accounting/api/{tenant-id}/companies/1/bookings/1982/booking-details/11298",
"partialPaymentAmount": 500
},
{
"bookingTypeCode": "AR_PREPAYMENT",
"bookingDetailUri": "/luz_accounting/api/{tenant-id}/companies/1/bookings/1983/booking-details/11302",
"partialPaymentAmount": 500
}
],
"subject": "Invoice with attachment and reconciliation",
"usingVAT": true,
"orderType": "INVOICE",
"documentDate": "2026-05-29",
"postMethod": "PRINT_AND_MANUAL_SEND"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Invoice persisted successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invoice"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/invoices/{id}": {
"get": {
"tags": [
"Finance"
],
"summary": "Get a single invoice by its numeric id.",
"description": "Returns the fully-enriched invoice document for the given id under the company resolved from the bearer JWT. The response includes order items enriched with inventory selection data and accounting booking-status fields (bookingStatus, bookingDueDate, bookingSealed) populated by luz_accounting. The caller must hold the FINANCE permission on the target company.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Numeric primary key of the invoice to retrieve. Obtain this from the id field of a previously created invoice (POST /core/v1/invoices).",
"required": true,
"schema": {
"type": "integer",
"example": 42
},
"example": 42
}
],
"responses": {
"200": {
"description": "Invoice found and returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invoice"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "No invoice with the given id exists for the authenticated company."
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/invoices/{id}/printed-document": {
"post": {
"tags": [
"Finance"
],
"summary": "Return the invoice as a PDF (rendering it if needed).",
"description": "Returns the invoice document as a binary application/pdf stream via the internal Klara printing pipeline (luz_web + Aspose Words), mirroring the behaviour of the Klara GUI. The caller must hold the FINANCE permission on the target company.printedFileId is stored on the invoice record. In both cases the response body is the binary PDF with a Content-Disposition: attachment header containing the suggested filename. This is a POST (not GET) because the first print persists the printedFileId.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the invoice to return as PDF. Must belong to the company resolved from the bearer JWT.",
"required": true,
"schema": {
"type": "integer",
"example": 42
},
"example": 42
}
],
"responses": {
"200": {
"description": "Invoice PDF returned as a binary application/pdf stream with a Content-Disposition: attachment header — either freshly rendered (first print) or the previously stored PDF (already printed).",
"content": {
"application/pdf": {}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Invoice not found."
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/invoices/{id}/send": {
"post": {
"tags": [
"Finance"
],
"summary": "Send a booked invoice (smart delivery or a forced channel).",
"description": "Sends an already-booked invoice to its recipient, synchronously, under the company resolved from the bearer JWT.channel for smart delivery: the system auto-routes through EPOST, EBILL, SEND_EMAIL and Print&Send and only fails if none can deliver. Provide channel to force that exact channel: if the recipient is not eligible (e.g. no email on file, not eBill-registered, Print&Send not subscribed) the call fails with 400. The invoice PDF is rendered on demand when it has not been printed yet.DRAFT and cancelled invoices are rejected with 400. Create/book it via POST /core/v1/invoices (status=INVOICED) first.channel uses the same values as Invoice.postMethod, except PRINT_AND_MANUAL_SEND, which is not a deliverable channel and is rejected with 400. Authentication is API key + bearer JWT; the caller must hold the FINANCE permission on the target company.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Numeric primary key of the booked invoice to send. Must belong to the company resolved from the bearer JWT. Obtain it from the id of a previously created invoice (POST /core/v1/invoices).",
"required": true,
"schema": {
"type": "integer",
"example": 42
},
"example": 42
},
{
"name": "channel",
"in": "query",
"description": "Forced distribution channel. Leave empty for smart delivery (auto-routing) — the default is no forced channel. Allowed values: EPOST, EBILL, SEND_EMAIL, A_POST, B_POST. PRINT_AND_MANUAL_SEND is rejected with 400 (not a deliverable channel).",
"required": false,
"schema": {
"enum": [
"A_POST",
"B_POST",
"SEND_EMAIL",
"PRINT_AND_MANUAL_SEND",
"EPOST",
"EBILL"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Invoice delivered. Returns the channel actually used, whether it was smart-routed, the OneAPI delivery id and the archived PDF's printedFileId.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendInvoiceResult"
}
}
}
},
"400": {
"description": "Invoice is DRAFT/cancelled, the channel is unsupported (PRINT_AND_MANUAL_SEND), the recipient is not eligible for the forced channel, or smart delivery found no channel.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "No invoice with the given id exists for the authenticated company."
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/invoices/next-invoice-number": {
"get": {
"tags": [
"Finance"
],
"summary": "Get the next available invoice number for the authenticated company.",
"description": "Returns the next available invoice number for the company resolved from the bearer JWT. The caller must hold the FINANCE permission on the target company. This operation is NOT idempotent — each successful call advances the persisted next-invoice-number counter on luzfin_finance, so the returned value is reserved and will not be returned again. Do not retry on success.",
"responses": {
"200": {
"description": "Next available invoice number returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NextInvoiceNumberResponse"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/order-documents/{order-type}/next-document-number": {
"get": {
"tags": [
"Finance"
],
"summary": "Get the next document number for a given order-document type.",
"description": "Returns the next available sequence number and its formatted document code for the authenticated company and the given order-type. Use the returned documentCode as invoiceCode / offerCode when subsequently creating a document with POST /core/v1/invoices. Side effect for INVOICE: the persisted counter is advanced on every call — do not call speculatively. Only meaningful for OFFER, CONFIRMATION, DELIVERY_NOTE, and INVOICE; other types always return documentNumber = 0. If the company has configured MANUAL numbering for the requested type, the downstream service returns HTTP 500 — check GET /core/v1/order-numbering-configurations first. The caller must hold the FINANCE permission on the target company.",
"parameters": [
{
"name": "order-type",
"in": "path",
"description": "Order-document type whose counter to advance. Meaningful values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE. Other enum values (CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE) are accepted but always return documentNumber = 0. An invalid value returns HTTP 400.",
"required": true,
"schema": {
"description": "Order-management document type. Used as the discriminator on OrderDocument.orderType.",
"enum": [
"OFFER",
"CONFIRMATION",
"DELIVERY_NOTE",
"INVOICE",
"CREDIT_NOTE",
"FRIENDLY_REMINDER",
"FIRST_REMINDER",
"SECOND_REMINDER",
"PAYSLIP",
"RECURRING_INVOICE_TEMPLATE"
],
"type": "string",
"example": "INVOICE",
"nullable": false
},
"example": "INVOICE"
}
],
"responses": {
"200": {
"description": "Next document number and formatted code for the requested order type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderNumberingResult"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/order-documents/filter/type-and-order-number": {
"get": {
"tags": [
"Finance"
],
"summary": "List order-management documents by type and order number.",
"description": "Returns every order-management document of the company resolved from the bearer JWT that has the given type and business order-number. Used to discover sibling documents on the same order chain (e.g. find the DELIVERY_NOTEs for an order number before creating an INVOICE from them). The caller must hold the FINANCE permission on the target company. This operation is idempotent and read-only — it can be safely retried.",
"parameters": [
{
"name": "order-number",
"in": "query",
"description": "Business order number shared by all documents in the same order chain (e.g. the order.orderNumber returned by POST /core/v1/invoices). Exact match. Required.",
"required": true,
"schema": {
"type": "integer",
"example": 377,
"nullable": false
},
"example": 377
},
{
"name": "type",
"in": "query",
"description": "Order-document type to filter by. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE. Required.",
"required": true,
"schema": {
"description": "Order-management document type. Used as the discriminator on OrderDocument.orderType.",
"enum": [
"OFFER",
"CONFIRMATION",
"DELIVERY_NOTE",
"INVOICE",
"CREDIT_NOTE",
"FRIENDLY_REMINDER",
"FIRST_REMINDER",
"SECOND_REMINDER",
"PAYSLIP",
"RECURRING_INVOICE_TEMPLATE"
],
"type": "string",
"example": "DELIVERY_NOTE",
"nullable": false
},
"example": "DELIVERY_NOTE"
}
],
"responses": {
"200": {
"description": "Matching order-management documents.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderDocument"
}
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/order-numbering-configurations": {
"get": {
"tags": [
"Finance"
],
"summary": "Get the order-numbering configuration for a document type.",
"description": "Returns the numbering strategy configured for the given order-type of the company resolved from the bearer JWT. Use this before creating a document to decide how to supply the document number in POST /core/v1/invoices: STANDARD — server auto-assigns; MANUAL — set invoiceCode yourself; CUSTOMISED — set invoiceCode to a value matching the returned format pattern. If no configuration has been saved by the company administrator, a default STANDARD configuration is returned. The caller must hold the FINANCE permission on the target company. This operation is idempotent and read-only.",
"parameters": [
{
"name": "order-type",
"in": "query",
"description": "Document type to retrieve the numbering configuration for. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE. Recommended — omitting it returns a generic default with a null orderType field.",
"required": false,
"schema": {
"description": "Order-management document type. Used as the discriminator on OrderDocument.orderType.",
"enum": [
"OFFER",
"CONFIRMATION",
"DELIVERY_NOTE",
"INVOICE",
"CREDIT_NOTE",
"FRIENDLY_REMINDER",
"FIRST_REMINDER",
"SECOND_REMINDER",
"PAYSLIP",
"RECURRING_INVOICE_TEMPLATE"
],
"type": "string",
"example": "INVOICE"
},
"example": "INVOICE"
}
],
"responses": {
"200": {
"description": "Numbering configuration for the requested document type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderNumberingConfiguration"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/orders/next-order-number": {
"get": {
"tags": [
"Finance"
],
"summary": "Get the next available order number for the authenticated company.",
"description": "Returns the next available business order number for the company resolved from the bearer JWT. Use the returned nextOrderNumber as the orderNumber field when subsequently creating an order. Not idempotent: each call reserves and advances the in-memory counter — call this immediately before creating the order and do not call speculatively. Gaps may appear in the sequence if the subsequent order creation fails. The caller must hold the FINANCE permission on the target company.",
"responses": {
"200": {
"description": "Next available order number for the authenticated company.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderNextNumberResult"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items": {
"post": {
"tags": [
"Payroll"
],
"summary": "Add a salary item to an employee's payslip.",
"description": "Adds a single salary item (Base / Percent / Quantity / Amount / Comments) to the employee's editable (non-sealed) payslip identified by payslipId, then recalculates that month unless recalculate=false. Returns the added salary item with its server-assigned id. This operation is not idempotent: repeated calls append duplicate items or throw an error when the item is not duplicatable (subject to the item's duplicatable flag). Prerequisite: call GET /payroll/employees/{employeeId}/addable-salary-items first — its response provides the contractId and payslipId to target and the addable codes; resolve employeeId beforehand via GET /employees/short-info. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION permission on that company.",
"parameters": [
{
"name": "contractId",
"in": "path",
"description": "Id of the employee's contract to add the salary item to. Obtained from the contractId field of the GET /payroll/employees/{employeeId}/addable-salary-items response — call that endpoint first to select the employee and obtain this id.",
"required": true,
"schema": {
"type": "integer",
"example": 1
},
"example": 1
},
{
"name": "payslipId",
"in": "path",
"description": "Id of the target (editable, non-sealed) payslip. Obtained from the payslipId field of the GET /payroll/employees/{employeeId}/addable-salary-items response — call that endpoint first to select the employee and obtain this id.",
"required": true,
"schema": {
"type": "integer",
"example": 26
},
"example": 26
},
{
"name": "recalculate",
"in": "query",
"description": "Whether to recalculate the payslip after adding the item. Defaults to true.",
"required": false,
"schema": {
"default": "true",
"type": "boolean",
"example": true
},
"example": true
}
],
"requestBody": {
"description": "Purpose: add one salary item to the target payslip. The code must be one of the addable salary items for this payslip, and only the value fields the item allows may be sent.GET /employees/short-info → provides employeeIdGET /payroll/employees/{employeeId}/addable-salary-items → provides the contractId and payslipId path parameters, plus salaryItems[].code (→ code) and each item's editableFields (which of baseValue/rate/quantity/value may be sent)code (string, required) — salary-type code from the addable-salary-items response.salaryItemValues (object, optional) — the numeric values; see below.remark (string, optional, max 1024) — free-text comment (GUI \"Comments\").salaryItemValues:baseValue — GUI \"Base\".rate — GUI \"Percent (%)\", but expressed as a decimal multiplier, not a percentage number: 1 = 100%, 0.5 = 50%, 2 = 200%. If GUI implementation wants to keep a normal percentage input for the user (e.g. typing 50 for 50%), it must divide that value by 100 before sending it here (50 / 100 = 0.5).quantity — GUI \"Quantity\".value — GUI \"Amount\".code must be addable to this payslip (returned by the addable-salary-items endpoint); only fields listed in the item's editableFields should be provided and the GUI implementation should also only show input boxes for those fields; with salary items that are not duplicatable (duplicatable=false), the GUI implementation should have a mechanism to recall the GET /payroll/employees/{employeeId}/addable-salary-items endpoint after each add to refresh the list of addable items and prevent adding duplicates, or automatically remove the added item from the list of addable items in the GUI; salaryItemValues.rate is a decimal multiplier (1 = 100%, 0.5 = 50%, 2 = 200%), not a percentage number — do not send a raw percentage like 50 for 50%, send 0.5.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PayslipSalaryItemRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PayslipSalaryItem"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/payroll/employees/{employeeId}/addable-salary-items": {
"get": {
"tags": [
"Payroll"
],
"summary": "Get the salary items that can be added to an employee's payslip.",
"description": "Resolves the employee's main (latest) contract and its editable payslip, then returns the salary-item types that can be added to that payslip as blank templates (numeric value fields cleared, distinct by code), together with the resolved contractId and payslipId so the response can be chained into the add-salary-item call. Prerequisite: call GET /employees/short-info first to resolve the employeeId path parameter from the returned entries' id field. When month is provided the specified month's payslip is used (read-only); when it is omitted the employee's current editable payslip is used, which may be computed on first access. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION permission on that company.",
"parameters": [
{
"name": "employeeId",
"in": "path",
"description": "Id of the employee whose addable salary items are resolved. Obtained from the id field of an entry returned by GET /employees/short-info.",
"required": true,
"schema": {
"type": "integer",
"example": 1
},
"example": 1
},
{
"name": "month",
"in": "query",
"description": "Payslip month in the format MM.yyyy (e.g. 06.2025). If omitted, the employee's current editable payslip is used.",
"required": false,
"schema": {
"type": "string",
"example": "06.2025"
},
"example": "06.2025"
},
{
"name": "Accept-Language",
"in": "header",
"description": "Preferred language for localised salary-item descriptions, as an IETF language tag. Examples: de-CH, fr-CH, it-CH, en. Defaults to the tenant's language when omitted.",
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddablePayslipSalaryItems"
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage1"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v1/vat-clearing-reports/{year}/{quarter}": {
"post": {
"tags": [
"Accounting"
],
"summary": "Get or recompute the VAT clearing report of a company for a given period.",
"description": "Returns the VAT clearing report of the caller's company for the requested calendar year and reporting quarter (quarter, semester or yearly). When recalculate=true the report is recomputed from the current bookings and the stored CALCULATED snapshot is rewritten before being returned; this is why the operation uses POST rather than GET. When recalculate=false the latest CALCULATED snapshot is returned as-is, or — if only a SEALED snapshot exists — that one. The caller must hold the ACCOUNTING permission on the targeted company.",
"parameters": [
{
"name": "quarter",
"in": "path",
"description": "Reporting period within the year. Allowed values: Q1, Q2, Q3, Q4, S1, S2, YEAR_NET_TAX_RATE, YEAR_EFFECTIVE.",
"required": true,
"schema": {
"description": "Reporting period of a VAT clearing report.",
"enum": [
"Q1",
"Q2",
"Q3",
"Q4",
"S1",
"S2",
"YEAR_NET_TAX_RATE",
"YEAR_EFFECTIVE"
],
"type": "string",
"example": "Q1"
},
"example": "Q1"
},
{
"name": "year",
"in": "path",
"description": "Calendar year of the reporting period.",
"required": true,
"schema": {
"type": "integer",
"example": 2024
},
"example": 2024
},
{
"name": "recalculate",
"in": "query",
"description": "If true, recompute the report from current bookings and overwrite the stored CALCULATED snapshot before returning. Defaults to false.",
"required": false,
"schema": {
"default": "false",
"type": "boolean",
"example": false
},
"example": false
},
{
"name": "Accept-Language",
"in": "header",
"description": "Preferred language for localized labels in the response. Examples: de-CH, de, fr-CH, it-CH, en.",
"required": false,
"schema": {
"type": "string",
"example": "de-CH"
},
"example": "de-CH"
}
],
"responses": {
"200": {
"description": "The VAT clearing report.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VatClearingReport"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"403": {
"description": "The current user is not allowed to access this company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"404": {
"description": "Resource not found"
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support."
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v2/tenants/companies": {
"get": {
"tags": [
"Company"
],
"summary": "Find KLARA business company of tenant",
"description": "Retrieve the business company of a tenant. Use your KLARA token from your username & password & tenant-id.",
"responses": {
"201": {
"description": "Company found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessCompany"
}
}
}
},
"401": {
"description": "Invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The user has been disabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong when find company",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Company"
],
"summary": "Update a KLARA business company",
"description": "A Klara user might have multiple tenants. Use this endpoint to update a KLARA business company. Use your KLARA token from your username & password & tenant-id.",
"requestBody": {
"description": "The updated company information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessCompany"
}
}
}
},
"responses": {
"201": {
"description": "Company updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessCompany"
}
}
}
},
"400": {
"description": "Invalid company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The user has been disabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong when updating tenant",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Company"
],
"summary": "Create a KLARA business company",
"description": "A Klara user might have multiple company tenants. Use this endpoint to create a business company and its correspondence tenant. Use your KLARA token from your username & password & tenant-id.",
"requestBody": {
"description": "The company information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BusinessCompany"
}
}
}
},
"responses": {
"201": {
"description": "Tenant and company created",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tenant"
}
}
}
}
},
"400": {
"description": "Invalid company data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The user has been disabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "API rate limit exceeded"
},
"500": {
"description": "Something went wrong when creating tenant and business company",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/core/v2/tenants/individuals/profile": {
"get": {
"tags": [
"Individual"
],
"summary": "[PREVIEW_API] Get profile from tenant's ID",
"responses": {
"200": {
"description": "Retrieved profile successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"participantId": {
"type": "string",
"readOnly": true,
"example": "969b2b24-5ffe-4b7c-b1e2-a2a59fb1acb5"
},
"firstName": {
"type": "string",
"example": "Nikola"
},
"lastName": {
"type": "string",
"example": "Tesla"
},
"email": {
"description": "Main email address",
"type": "string",
"example": "email@klara.ch"
},
"tenantEntryType": {
"description": "Tenant entry type of the profile",
"type": "string",
"example": "INDIVIDUAL"
}
}
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"404": {
"description": "Profile not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Individual"
],
"summary": "[PREVIEW_API] Create profile",
"responses": {
"200": {
"description": "Created profile successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"participantId": {
"type": "string",
"readOnly": true,
"example": "969b2b24-5ffe-4b7c-b1e2-a2a59fb1acb5"
},
"firstName": {
"type": "string",
"example": "Nikola"
},
"lastName": {
"type": "string",
"example": "Tesla"
},
"email": {
"description": "Main email address",
"type": "string",
"example": "email@klara.ch"
},
"tenantEntryType": {
"description": "Tenant entry type of the profile",
"type": "string",
"example": "INDIVIDUAL"
}
}
}
}
}
},
"400": {
"description": "Data invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"401": {
"description": "No Authorization header found or invalid token"
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
},
"500": {
"description": "Something went wrong on our side while processing the request. Please kindly contact our support.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
}
}
},
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
]
}
}
},
"components": {
"schemas": {
"AccessTokenResponse": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"expires_in": {
"format": "int64",
"type": "integer"
},
"refresh_expires_in": {
"format": "int64",
"type": "integer"
},
"refresh_token": {
"type": "string"
},
"token_type": {
"type": "string"
},
"id_token": {
"type": "string"
},
"not-before-policy": {
"format": "int32",
"type": "integer"
},
"session_state": {
"type": "string"
},
"otherClaims": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
},
"AddablePayslipSalaryItems": {
"description": "The salary items that can be added to an employee's editable payslip, plus the resolved contract/payslip to chain into the add-salary-item call.",
"type": "object",
"properties": {
"employeeId": {
"format": "int64",
"description": "Id of the employee the addable salary items were resolved for.",
"type": "integer",
"example": 3487
},
"contractId": {
"format": "int64",
"description": "Id of the employee's resolved main (latest) contract. Pass this to the add-salary-item call.",
"type": "integer",
"example": 9021
},
"payslipId": {
"format": "int64",
"description": "Id of the resolved editable payslip. Pass this to the add-salary-item call.",
"type": "integer",
"example": 9542
},
"periodFrom": {
"format": "date-time",
"description": "Month (first day) of the resolved payslip (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2018-03-01T00:00:00Z"
},
"salaryItems": {
"description": "Addable salary items as blank templates (value fields cleared), distinct by code.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AddableSalaryItem"
}
}
}
},
"AddableSalaryItem": {
"description": "A salary-item type that can be added to an employee's payslip (blank template, value fields cleared).",
"type": "object",
"properties": {
"code": {
"description": "Salary-type code. Send this as the salary item code when adding it to the payslip.",
"type": "string",
"example": "1005"
},
"name": {
"description": "Canonical (non-localized) name of the salary item.",
"type": "string",
"example": "Hourly Salary"
},
"description": {
"description": "Localised description/label of the salary item (localised via the Accept-Language header).",
"type": "string",
"example": "Stundenlohn"
},
"editableFields": {
"description": "Comma-separated list of the value fields that can be provided when adding this salary item (baseValue, rate, quantity, value). The GUI implementation must base on this list to only show input box for fields that exist in this list.",
"type": "string",
"example": "baseValue,quantity"
},
"duplicatable": {
"description": "Whether more than one instance of this salary item can be added to the same payslip. When false, only one instance of this salary item can be added, try to add another one will result in an error.",
"type": "boolean",
"example": true
},
"showOnPayslip": {
"description": "Whether the salary item is shown on the payslip.",
"type": "boolean",
"example": true
},
"employerRelated": {
"description": "Whether the salary item is employer-related (as opposed to employee-related).",
"type": "boolean",
"example": false
},
"paymentTypeSit": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentType"
},
{
"description": "How the salary item is paid out. Allowed values: BANK, PAYINSLIP, CASH.",
"example": "BANK"
}
]
},
"salaryItemTypeId": {
"format": "int64",
"description": "Id of the underlying salary-item type definition.",
"type": "integer",
"example": 42
},
"accountingGroup": {
"description": "Accounting group the salary item belongs to.",
"type": "string",
"example": "SALARY"
},
"printSequence": {
"format": "int32",
"description": "Print/order sequence of the salary item on the payslip.",
"type": "integer",
"example": 100
}
}
},
"Address": {
"description": "An Address of a customer.",
"required": [
"addressLines",
"addressType",
"cityName",
"countryIso2Code"
],
"type": "object",
"properties": {
"id": {
"description": "Id of this Address. Does not need to be included when creating customer",
"type": "string",
"example": "1"
},
"validFrom": {
"format": "date",
"description": "The timestamp from which this address is valid",
"type": "string"
},
"validTo": {
"format": "date",
"description": "The timestamp to which this address is valid",
"type": "string"
},
"addressLines": {
"description": "The address lines for this Address",
"type": "string",
"example": "Chemin de la Caquerette 12"
},
"addressType": {
"description": "The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE. ",
"pattern": "\\S",
"type": "string",
"example": "WORK",
"nullable": false
},
"cityName": {
"description": "Name of this City",
"pattern": "\\S",
"type": "string",
"example": "Bern",
"nullable": false
},
"cityZipCode": {
"description": "The postal code of a city for this address",
"type": "string",
"example": "3003"
},
"countryIso2Code": {
"description": "2 letter country code. For company, only accept Switzerland",
"pattern": "\\S",
"type": "string",
"example": "CH",
"nullable": false
},
"countryIso3Code": {
"description": "3 letter country code. For company, only accept Switzerland",
"type": "string",
"example": "CHE"
},
"countryNumericCode": {
"description": "ISO-numeric code. For company, only accept Switzerland",
"type": "string",
"example": "756"
},
"city_href": {
"description": "The path to get City object by city's id, /cities/{}",
"type": "string",
"readOnly": true,
"example": "https://api.klara.ch/core/latest/cities/1"
},
"definitionName": {
"description": "definition name of this address; in case main address, value is null; else value is not blank",
"type": "string",
"example": "2nd address"
},
"additionalAddress": {
"description": "Additional address for more specific",
"type": "string",
"example": "No. 13, street 123"
}
}
},
"ApplicabilityVatCaseType": {
"enum": [
"REVENUE",
"COST"
],
"type": "string"
},
"Article": {
"description": "An article.",
"required": [
"nameDE",
"unitDE",
"accountingTags",
"articleNumber",
"productType"
],
"type": "object",
"properties": {
"id": {
"description": "Id of the article. Does not need to be included when creating article",
"type": "string",
"readOnly": true,
"example": "1"
},
"nameDE": {
"description": "Name of the article in German",
"type": "string"
},
"nameEN": {
"description": "Name of the article in English",
"type": "string"
},
"nameFR": {
"description": "Name of the article in French",
"type": "string"
},
"nameIT": {
"description": "Name of the article in Italian",
"type": "string"
},
"descriptionDE": {
"description": "Description of the article in German",
"type": "string"
},
"descriptionEN": {
"description": "Description of the article in English",
"type": "string"
},
"descriptionFR": {
"description": "Description of the article in French",
"type": "string"
},
"descriptionIT": {
"description": "Description of the article in Italian",
"type": "string"
},
"extendedDescriptionDE": {
"description": "Extended description of the article in German",
"type": "string"
},
"extendedDescriptionEN": {
"description": "Extended description of the article in English",
"type": "string"
},
"extendedDescriptionFR": {
"description": "Extended description of the article in French",
"type": "string"
},
"extendedDescriptionIT": {
"description": "Extended description of the article in Italian",
"type": "string"
},
"unitDE": {
"description": "Unit of the article in German",
"type": "string"
},
"unitEN": {
"description": "Unit of the article in English",
"type": "string"
},
"unitFR": {
"description": "Unit of the article in French",
"type": "string"
},
"unitIT": {
"description": "Unit of the article in Italian",
"type": "string"
},
"barcode": {
"description": "Barcode of the article",
"type": "string"
},
"usePos": {
"description": "Decides if this article is used for POS or not",
"type": "boolean"
},
"pricePeriods": {
"description": "Price periods for the article.true, VAT is baked into the displayed prices. When false, VAT is shown as a separate line item. Returns false when no configuration record has been set for the company.",
"type": "boolean",
"example": false
}
}
},
"CompanyDocumentUploadForm": {
"description": "Multipart form body: a document category and a single file (max 25 MB).",
"required": [
"category",
"file"
],
"type": "object",
"properties": {
"category": {
"description": "Document category. Determines where the file is stored and which downstream post-processing is triggered (e.g. LIABILITY_UPLOAD triggers asynchronous AI analysis). Important: For the create booking functionality, only LIABILITY_UPLOAD is allowed — the booking creation GUI must always use LIABILITY_UPLOAD when uploading documents in this context.",
"enum": [
"SALARY_STATEMENTS",
"YEARLY_REPORTS",
"PAYMENT_FILES",
"INSURANCE_CERTIFICATES",
"SALARY_TRANSMISSIONS",
"OWN_DOCUMENTS",
"LIABILITY_UPLOAD",
"EXPENSES",
"LIABILITIES"
],
"type": "string"
},
"file": {
"format": "binary",
"description": "The document file to upload. Maximum size 25 MB. Allowed file types are enforced by the downstream service.",
"type": "string"
}
}
},
"CompanyVAT": {
"description": "A Company VAT.",
"type": "object",
"properties": {
"id": {
"description": "Id of the company VAT.",
"type": "string",
"example": "123"
},
"hasVat": {
"description": "Flag mark the company have VAT or not.",
"type": "boolean"
},
"vatNumber": {
"description": "The VAT number.",
"type": "string",
"example": "ABC-123"
},
"validFrom": {
"format": "date",
"description": "The company VAT is valid from this time.",
"type": "string"
},
"validTo": {
"format": "date",
"description": "The company VAT is invalid after this time.",
"type": "string"
},
"companyId": {
"format": "int64",
"description": "Id of the company",
"type": "integer",
"example": 1
},
"vats": {
"description": "This is list VAT value of the company.",
"type": "array",
"items": {
"$ref": "#/components/schemas/VAT"
}
}
}
},
"Correspondence": {
"enum": [
"MAIL",
"EMAIL"
],
"type": "string"
},
"Country": {
"description": "A Country that this partner locates.",
"type": "object",
"properties": {
"id": {
"type": "string",
"readOnly": true
},
"countryName": {
"description": "Name of this Country",
"type": "string",
"example": "Schweiz"
},
"iso2Code": {
"description": "2 letter country code",
"type": "string",
"example": "CH"
},
"iso3Code": {
"description": "3 letter country code",
"type": "string",
"example": "CHE"
},
"phoneCode": {
"description": "Country calling code",
"type": "string",
"example": 41
},
"numericCode": {
"description": "ISO-numeric code",
"type": "string",
"example": "756"
}
}
},
"CustomField": {
"description": "A custom field.",
"type": "object",
"properties": {
"id": {
"description": "Id of this custom field. Does not need to be included when creating CustomerContact",
"type": "string",
"readOnly": true,
"example": "1"
},
"customName": {
"description": "name of this custom field",
"type": "string",
"example": "name at home"
},
"customValue": {
"description": "value of this custom field",
"type": "string",
"example": "John Henry"
}
}
},
"Customer": {
"description": "A customer.",
"required": [
"customerType"
],
"type": "object",
"properties": {
"id": {
"description": "Id of this Customer. Does not need to be included when creating customer",
"type": "string",
"readOnly": true,
"example": "1"
},
"person": {
"allOf": [
{
"$ref": "#/components/schemas/Person"
},
{
"description": "The Person object for when the customer type is Person."
}
]
},
"company": {
"allOf": [
{
"$ref": "#/components/schemas/Company"
},
{
"description": "The Company object for when the customer type is Person."
}
]
},
"priceCategory": {
"description": "You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.",
"type": "string",
"example": "Sale price"
},
"customerType": {
"allOf": [
{
"$ref": "#/components/schemas/CustomerType"
},
{
"description": "The type of this partner. Could be either Person or Company.",
"example": "PERSON",
"nullable": false
}
]
},
"_links": {
"allOf": [
{
"$ref": "#/components/schemas/RepresentationLinks"
},
{
"readOnly": true
}
]
}
}
},
"CustomerContact": {
"description": "A customer's contact.",
"required": [
"firstName",
"lastName"
],
"type": "object",
"properties": {
"id": {
"description": "Id of this contact. Does not need to be included when creating CustomerContact",
"type": "string",
"readOnly": true,
"example": "1"
},
"imageId": {
"description": "Id of this contact's image. Does not need to be included when creating CustomerContact",
"type": "string",
"readOnly": true,
"example": "1"
},
"salutation": {
"allOf": [
{
"$ref": "#/components/schemas/Salutation"
},
{
"description": "Salutation for this contact",
"example": "MALE"
}
]
},
"firstName": {
"description": "First name of this contact",
"type": "string",
"example": "John"
},
"lastName": {
"description": "Last name of this contact",
"type": "string",
"example": "Henry"
},
"email": {
"description": "Email of this contact",
"type": "string",
"example": "john.henry@gmail.com"
},
"website": {
"description": "Website of this contact",
"type": "string",
"example": "www.youtube.com"
},
"additionalAddressDefinition": {
"description": "Additional address definition of this contact",
"type": "string"
},
"phones": {
"description": "Phone number list of this contact",
"type": "array",
"items": {
"$ref": "#/components/schemas/Phone"
}
},
"categories": {
"description": "Category list of this contact",
"type": "array",
"items": {
"type": "string"
}
},
"onlinePlatforms": {
"description": "The list of online platforms that this contact uses",
"type": "array",
"items": {
"$ref": "#/components/schemas/OnlinePlatform"
}
},
"customFields": {
"description": "The list of custom information of this contact",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"function": {
"description": "Function of this contact",
"type": "string"
},
"birthday": {
"format": "date",
"description": "Birth date of this person in ISO 8601 format (yyyy-mm-dd)",
"type": "string",
"example": "2020-12-20"
},
"note": {
"description": "Note of this contact",
"type": "string",
"example": "this is a important contact."
}
}
},
"CustomerType": {
"enum": [
"COMPANY",
"PERSON"
],
"type": "string"
},
"DimensionUnit": {
"description": "Dimension unit used for shipping of the article",
"enum": [
"CENTIMETER",
"METER"
],
"type": "string"
},
"Email": {
"description": "An Email address.",
"required": [
"type"
],
"type": "object",
"properties": {
"id": {
"description": "Id of this Email. Does not need to be included when creating customer",
"type": "string",
"example": "1"
},
"emailAddress": {
"description": "Email address",
"type": "string",
"example": "example@gmail.com"
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EmailType"
},
{
"description": "Type of this email",
"enum": [
"PRIVATE",
"WORK",
"OFFICE"
],
"example": "PRIVATE",
"nullable": false
}
]
}
}
},
"EmailType": {
"enum": [
"PRIVATE",
"WORK",
"OFFICE",
"OTHER"
],
"type": "string"
},
"ErrorMessage": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"createdTime": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"detail": {
"type": "string",
"deprecated": true
}
}
},
"ErrorMessage1": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"createdTime": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"detail": {
"type": "string"
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"description": "Summary of the error response",
"type": "string"
},
"error_description": {
"description": "Description of the error response",
"type": "string"
}
}
},
"FileType": {
"enum": [
"JSON",
"CSV"
],
"type": "string"
},
"FilterAssigningGroup": {
"description": "A bunch of article ids need to be assigned the filter",
"type": "object",
"properties": {
"assignedPosArticleIds": {
"description": "Article ids will have the filter as a pos filter",
"uniqueItems": true,
"type": "array",
"items": {
"type": "string"
}
},
"assignedOnlineShopArticleIds": {
"description": "Article ids will have the filter as a online shop filter",
"uniqueItems": true,
"type": "array",
"items": {
"type": "string"
}
},
"assignedBookingArticleIds": {
"description": "Article ids will have the filter as a booking filter",
"uniqueItems": true,
"type": "array",
"items": {
"type": "string"
}
}
}
},
"InventoryNumberType": {
"enum": [
"NO_NUMBER",
"BATCH_NUMBER",
"SERIAL_NUMBER"
],
"type": "string"
},
"Invoice": {
"description": "An invoice document (creation or update). The polymorphic discriminator orderType is always INVOICE. Server-managed read-only fields (vatDate, lastModified, createDate, bookingDueDate, bookingNumbers, businessCaseId) are populated on the response.",
"required": [
"invoiceCode"
],
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.",
"type": "integer",
"example": 0
},
"orderType": {
"description": "Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.",
"default": "INVOICE",
"type": "string",
"example": "INVOICE"
},
"status": {
"description": "Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.",
"type": "string",
"example": "INVOICED"
},
"invoiceCode": {
"description": "Human-readable invoice code. Required and unique per company.",
"maxLength": 64,
"pattern": "\\S",
"type": "string",
"example": "INV-2026-001",
"nullable": false
},
"invoiceNumber": {
"format": "int64",
"description": "Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.",
"type": "integer",
"example": 2026001
},
"documentDate": {
"format": "date",
"description": "Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.",
"type": "string",
"example": "2026-05-28"
},
"paymentDate": {
"format": "date",
"description": "Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.",
"type": "string",
"example": "2026-06-27"
},
"deliveryDate": {
"format": "date",
"description": "Service delivery date (ISO 8601).",
"type": "string",
"example": "2026-05-25"
},
"issuedDate": {
"format": "date",
"description": "Date the invoice was issued (ISO 8601).",
"type": "string",
"example": "2026-05-28"
},
"servicePeriodFrom": {
"format": "date",
"description": "Service period start date (ISO 8601).",
"type": "string",
"example": "2026-05-01"
},
"servicePeriodTo": {
"format": "date",
"description": "Service period end date (ISO 8601).",
"type": "string",
"example": "2026-05-31"
},
"servicePeriodPattern": {
"description": "Service period pattern label (e.g. MONTHLY, YEARLY).",
"maxLength": 32,
"type": "string",
"example": "MONTHLY"
},
"vatDate": {
"format": "date",
"description": "VAT date. Server-managed (read-only).",
"type": "string"
},
"bookingDueDate": {
"format": "date",
"description": "Booking due date returned by accounting. Server-managed (read-only).",
"type": "string"
},
"lastModified": {
"format": "date-time",
"description": "Last modification timestamp. Server-managed (read-only).",
"type": "string"
},
"createDate": {
"format": "date-time",
"description": "Creation timestamp. Server-managed (read-only).",
"type": "string"
},
"amount": {
"description": "Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.",
"type": "number",
"example": 1080
},
"usingVAT": {
"description": "Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox \"VAT included in amount of each item\". true = amounts already include VAT (INCLUDE_VAT); false = VAT is added on top of the net amounts (EXCLUDE_VAT). It does not turn VAT on or off — whether VAT applies at all is governed by the company's VAT registration. Use GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).",
"default": "false",
"type": "boolean",
"example": true
},
"usingExportVat": {
"description": "Export invoice flag — the GUI \"Export\" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.",
"default": "false",
"type": "boolean",
"example": false
},
"subject": {
"description": "Free-text invoice subject.",
"maxLength": 1024,
"type": "string",
"example": "Invoice 2026-001"
},
"closeAndSignature": {
"description": "Free-text closing remarks / signature block.",
"maxLength": 4096,
"type": "string",
"example": "Thank you for your business."
},
"ourReference": {
"description": "Internal sender reference.",
"maxLength": 128,
"type": "string",
"example": "ACC-2026"
},
"yourReference": {
"description": "Customer-side reference (e.g. PO number).",
"maxLength": 128,
"type": "string",
"example": "PO-9981"
},
"companyCityAndDate": {
"description": "Header line such as 'Zurich, 28.05.2026'.",
"maxLength": 256,
"type": "string",
"example": "Zurich, 28.05.2026"
},
"postMethod": {
"description": "Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.",
"type": "string",
"example": "SEND_EMAIL"
},
"delivery": {
"description": "Delivery method label (free text).",
"maxLength": 64,
"type": "string",
"example": "DHL"
},
"ibanNumberCHF": {
"description": "CHF IBAN for payment. Validated by downstream service.",
"type": "string",
"example": "CH9300762011623852957"
},
"ibanNumberCHW": {
"description": "WIR-franc IBAN for payment.",
"type": "string",
"example": "CH9300762011623852957"
},
"wirAcceptanceRate": {
"description": "WIR acceptance percentage.",
"type": "number",
"example": 0
},
"referenceNumber": {
"description": "QR / ISR reference number.",
"maxLength": 64,
"type": "string",
"example": "21 00000 00003 13947 14300 09017"
},
"qrInvoice": {
"description": "When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.",
"default": "false",
"type": "boolean",
"example": true
},
"fromAutoInvoicing": {
"description": "Indicates the invoice was generated by auto-invoicing. Defaults to false.",
"default": "false",
"type": "boolean",
"example": false
},
"fromInvoiceRun": {
"description": "Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.",
"default": "false",
"type": "boolean",
"example": false
},
"invoiceType": {
"description": "Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.",
"type": "string",
"example": "MANUAL"
},
"originDistributionMethod": {
"description": "Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.",
"type": "string",
"example": "SEND_EMAIL"
},
"templateId": {
"format": "int64",
"description": "Template id used to create this invoice.",
"type": "integer",
"example": 0
},
"runHistoryId": {
"format": "int64",
"description": "Recurring invoice run history id.",
"type": "integer",
"example": 0
},
"settledAmount": {
"description": "Klara-Pay settled amount (online shop only).",
"type": "number",
"example": 0
},
"bookingNumbers": {
"description": "Accounting booking-number string. Server-managed (read-only).",
"type": "string"
},
"businessCaseId": {
"format": "int64",
"description": "Accounting business case id. Server-managed (read-only).",
"type": "integer"
},
"bookingStatus": {
"description": "Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).",
"type": "string"
},
"bookingMessage": {
"description": "Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). Server-managed (read-only).",
"type": "string"
},
"bookingSealed": {
"description": "Whether the booking has been finalized. Server-managed (read-only).",
"type": "boolean"
},
"fiscalYearHasCreatedAuto": {
"description": "Whether a fiscal year was auto-created during booking. Server-managed (read-only).",
"type": "boolean"
},
"createBy": {
"description": "Server-assigned audit user (token subject). Server-managed (read-only).",
"type": "string"
}
}
},
"LegalForm": {
"enum": [
"LIMITED_LIABILITY",
"CORPORATION",
"OR",
"INDIVIDUALLY_OWNED_COMPANY",
"ASSOCIATION",
"SIMPLE_PARTNERSHIP",
"GENERAL_PARTNERSHIP",
"LIMITED_PARTNERSHIP",
"COOPERATIVE_COMPANY",
"FOUNDATION",
"IOER"
],
"type": "string"
},
"Link": {
"description": "Link metadata",
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
},
"NextInvoiceNumberResponse": {
"description": "Response wrapper for the next available invoice number for the authenticated company.",
"type": "object",
"properties": {
"nextInvoiceNumber": {
"format": "int64",
"description": "The next available invoice number reserved for the authenticated company. Each successful call advances the persisted counter; the value is therefore unique per call.",
"type": "integer",
"example": 2026001
}
}
},
"OnlinePlatform": {
"description": "An online platform.",
"type": "object",
"properties": {
"id": {
"description": "Id of this Online platform. Does not need to be included when creating Customer.",
"type": "string",
"readOnly": true,
"example": "1"
},
"platformName": {
"allOf": [
{
"$ref": "#/components/schemas/OnlinePlatformType"
},
{
"description": "Name of the platform that this customer uses",
"example": "FACEBOOK"
}
]
},
"platformValue": {
"description": "Url of customer's online platform/webpage",
"type": "string",
"example": "www.linkedin.com/abc"
}
}
},
"OnlinePlatformType": {
"enum": [
"FACEBOOK",
"GOOGLE_PLUS",
"INSTAGRAM",
"LINKEDIN",
"PINTEREST",
"SKYPE",
"SNAPCHAT",
"TWITTER",
"WHATSAPP",
"XING",
"YOUTUBE"
],
"type": "string"
},
"OrderDocument": {
"description": "An order-management document — offer, confirmation, delivery-note, invoice, credit note or recurring invoice template. The polymorphic discriminator orderType identifies the concrete subtype. Server-managed fields (vatDate, lastModified, createDate) are populated on the response.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Document id (database primary key).",
"type": "integer",
"example": 1234
},
"orderType": {
"description": "Polymorphic discriminator. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE.",
"type": "string",
"example": "DELIVERY_NOTE"
},
"status": {
"description": "Document status (subtype-specific). For invoices: DRAFT, INVOICED, SENT, PAID, CANCELLED.",
"type": "string",
"example": "SENT"
},
"documentDate": {
"format": "date",
"description": "Document creation/business date (ISO 8601).",
"type": "string",
"example": "2026-05-28"
},
"issuedDate": {
"format": "date",
"description": "Date the document was issued (ISO 8601).",
"type": "string",
"example": "2026-05-28"
},
"amount": {
"description": "Document gross total (incl. VAT when applicable).",
"type": "number",
"example": 500
},
"ourReference": {
"description": "Internal sender reference.",
"type": "string",
"example": "ACC-2026"
},
"yourReference": {
"description": "Customer-side reference (e.g. PO number).",
"type": "string",
"example": "PO-9981"
},
"subject": {
"description": "Free-text document subject.",
"type": "string",
"example": "Delivery note 377"
},
"closeAndSignature": {
"description": "Free-text closing remarks / signature block.",
"type": "string",
"example": "Thank you for your business."
},
"companyCityAndDate": {
"description": "Header line such as 'Zurich, 28.05.2026'.",
"type": "string",
"example": "Zurich, 28.05.2026"
},
"usingVAT": {
"description": "Whether VAT is applied on this document.",
"default": "false",
"type": "boolean",
"example": true
},
"vatDate": {
"format": "date",
"description": "VAT date. Server-managed (read-only).",
"type": "string"
},
"printedFileId": {
"description": "Document file id of the rendered PDF (if any).",
"type": "string",
"example": "1771764"
}
}
},
"OrderNextNumberResult": {
"type": "object",
"properties": {
"nextOrderNumber": {
"format": "int32",
"description": "The next available business order number for the authenticated company. Reserved exclusively for this call — use it as the orderNumber when subsequently creating the order. Gaps may appear in the sequence if the order creation fails after this call.",
"type": "integer",
"example": 10041
}
}
},
"OrderNumberingConfiguration": {
"type": "object",
"properties": {
"orderType": {
"allOf": [
{
"$ref": "#/components/schemas/OrderType"
},
{
"description": "Order-document type this configuration applies to.",
"example": "INVOICE"
}
]
},
"orderNumberingType": {
"allOf": [
{
"$ref": "#/components/schemas/OrderNumberingType"
},
{
"description": "Strategy used to assign document numbers. STANDARD: server auto-increments from startingNumber; MANUAL: caller must supply a number in POST /invoices; CUSTOMISED: caller must supply a code matching format.",
"example": "STANDARD"
}
]
},
"startingNumber": {
"format": "int64",
"description": "The first number in the auto-increment sequence (relevant for STANDARD). Null when not configured.",
"type": "integer",
"example": 1000
},
"increment": {
"format": "int64",
"description": "Step size between successive auto-incremented numbers (relevant for STANDARD). Null when not configured.",
"type": "integer",
"example": 1
},
"format": {
"description": "Alphanumeric format pattern for CUSTOMISED numbering (e.g. INV-{YYYY}-{SEQ}). Null when not configured.",
"type": "string",
"example": "INV-2026-{SEQ}"
}
}
},
"OrderNumberingResult": {
"type": "object",
"properties": {
"orderType": {
"allOf": [
{
"$ref": "#/components/schemas/OrderType"
},
{
"description": "Order-document type this result applies to.",
"example": "INVOICE"
}
]
},
"orderNumberingType": {
"allOf": [
{
"$ref": "#/components/schemas/OrderNumberingType"
},
{
"description": "Numbering strategy for this document type: STANDARD (server auto-assigns), MANUAL (caller supplies invoiceCode), CUSTOMISED (caller supplies formatted code).",
"example": "STANDARD"
}
]
},
"startingNumber": {
"format": "int64",
"description": "Starting sequence number for STANDARD and CUSTOMISED strategies.",
"type": "integer",
"example": 1000
},
"increment": {
"format": "int64",
"description": "Step size between successive auto-incremented numbers.",
"type": "integer",
"example": 1
},
"format": {
"description": "Alphanumeric prefix for CUSTOMISED numbering (the server appends the sequence number).",
"type": "string",
"example": "INV-2026-"
},
"documentNumber": {
"format": "int64",
"description": "The next document number to use (the sequence integer). For INVOICE this counter is persisted on every call — do not call speculatively.",
"type": "integer",
"example": 1001
},
"documentCode": {
"description": "The next document code to use as invoiceCode / offerCode. For STANDARD and MANUAL this equals String.valueOf(documentNumber); for CUSTOMISED it equals format + documentNumber (e.g. \"INV-2026-1001\").",
"type": "string",
"example": "1001"
}
}
},
"OrderNumberingType": {
"description": "Strategy used to assign document numbers for an order type. STANDARD — server auto-increments; MANUAL — caller supplies the number; CUSTOMISED — caller supplies a formatted code matching the configured pattern.",
"enum": [
"STANDARD",
"MANUAL",
"CUSTOMISED"
],
"type": "string"
},
"OrderType": {
"description": "Order-management document type. Used as the discriminator on OrderDocument.orderType.",
"enum": [
"OFFER",
"CONFIRMATION",
"DELIVERY_NOTE",
"INVOICE",
"CREDIT_NOTE",
"FRIENDLY_REMINDER",
"FIRST_REMINDER",
"SECOND_REMINDER",
"PAYSLIP",
"RECURRING_INVOICE_TEMPLATE"
],
"type": "string"
},
"PaymentType": {
"enum": [
"BANK",
"PAYINSLIP",
"CASH"
],
"type": "string"
},
"PayslipSalaryItem": {
"description": "A salary item added to a payslip, with its server-assigned id.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Server-assigned id of the added salary item (present in the response only).",
"type": "integer",
"example": 778812
},
"code": {
"description": "Salary-type code of the added salary item.",
"type": "string",
"example": "1005"
},
"salaryItemValues": {
"allOf": [
{
"$ref": "#/components/schemas/PayslipSalaryItemValues"
},
{
"description": "The numeric value fields (Base / Percent / Quantity / Amount) of the added salary item."
}
]
},
"remark": {
"description": "Free-text comment attached to the salary item (GUI \"Comments\").",
"type": "string",
"example": "Adjustment for March"
}
}
},
"PayslipSalaryItemRequest": {
"description": "The salary item to add to a payslip: the salary-type code plus its numeric values and an optional comment.",
"required": [
"code"
],
"type": "object",
"properties": {
"code": {
"description": "Salary-type code identifying the item to add. Must be one of the codes returned by GET /payroll/employees/{employeeId}/addable-salary-items (salaryItems[].code).",
"maxLength": 64,
"pattern": "\\S",
"type": "string",
"example": "1005",
"nullable": false
},
"salaryItemValues": {
"allOf": [
{
"$ref": "#/components/schemas/PayslipSalaryItemValues"
},
{
"description": "The numeric value fields (Base / Percent / Quantity / Amount). Only fields listed in the salary item's editableFields, which are also returned by GET /payroll/employees/{employeeId}/addable-salary-items (salaryItems[].editableFields), should be provided."
}
]
},
"remark": {
"description": "Optional free-text comment (GUI \"Comments\").",
"maxLength": 1024,
"type": "string",
"example": "Adjustment for March"
}
}
},
"PayslipSalaryItemValues": {
"description": "Numeric value fields of a salary item (GUI Base / Percent / Quantity / Amount). Only fields listed in the salary item's editableFields may be provided.",
"type": "object",
"properties": {
"baseValue": {
"description": "GUI \"Base\" value.",
"type": "number",
"example": 5000
},
"rate": {
"description": "GUI \"Percent (%)\" value, expressed as a decimal multiplier — NOT a percentage number. 1 = 100%, 0.5 = 50%, 2 = 200%. If GUI implementation wants to keep a normal percentage input for the user (typing 50 for 50%) instead of a multiplier (0.5), it must divide that input by 100 before sending it here (50 / 100 = 0.5).",
"type": "number",
"example": 0.5
},
"quantity": {
"description": "GUI \"Quantity\" value.",
"type": "number",
"example": 1
},
"value": {
"description": "GUI \"Amount\" value.",
"type": "number",
"example": 425
}
}
},
"PeriodOfYear": {
"description": "Reporting period of a VAT clearing report.",
"enum": [
"Q1",
"Q2",
"Q3",
"Q4",
"S1",
"S2",
"YEAR_NET_TAX_RATE",
"YEAR_EFFECTIVE"
],
"type": "string",
"example": "Q1"
},
"Person": {
"description": "A partner person.",
"required": [
"correspondence",
"salutation",
"firstName",
"lastName"
],
"type": "object",
"properties": {
"website": {
"description": "The website address of this customer",
"type": "string",
"example": "www.my-company.com"
},
"categories": {
"description": "Add one or more categories to this customer that you can use as filter criteria for selecting partners",
"type": "array",
"items": {
"type": "string"
}
},
"onlinePlatforms": {
"description": "The list of online platforms that this customer uses",
"type": "array",
"items": {
"$ref": "#/components/schemas/OnlinePlatform"
}
},
"language": {
"description": "The main language that this partner uses, valid values is [en, de, fr, it]",
"type": "string",
"example": "en"
},
"responsibleCounterpart": {
"description": "The name of a contact person for this customer",
"type": "string",
"example": "Mr. Marc"
},
"correspondence": {
"allOf": [
{
"$ref": "#/components/schemas/Correspondence"
},
{
"description": "The preferred method of correspondence, how this customer wants to receive the pay slips by default",
"example": "MAIL",
"nullable": false
}
]
},
"id": {
"description": "Id of this person. Does not need to be included when creating customer",
"type": "string",
"example": "1"
},
"salutation": {
"allOf": [
{
"$ref": "#/components/schemas/Salutation"
},
{
"description": "Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]",
"example": "MALE",
"nullable": false
}
]
},
"firstName": {
"description": "First name of this person",
"pattern": "\\S",
"type": "string",
"example": "John",
"nullable": false
},
"lastName": {
"description": "Last name of this person",
"pattern": "\\S",
"type": "string",
"example": "Henry",
"nullable": false
},
"birthday": {
"format": "date",
"description": "Birth date of this person in ISO 8601 format (yyyy-MM-dd)",
"type": "string",
"example": "2020-01-20"
},
"addresses": {
"description": "Address list of this person",
"type": "array",
"items": {
"$ref": "#/components/schemas/Address"
}
},
"phones": {
"description": "Phone number list of this person",
"type": "array",
"items": {
"$ref": "#/components/schemas/Phone"
}
},
"emails": {
"description": "Email list of this person",
"type": "array",
"items": {
"$ref": "#/components/schemas/Email"
}
},
"personNumber": {
"description": "This is a number the KLARA user can give to this customer/partner/supplier",
"type": "string"
}
}
},
"Phone": {
"description": "A phone number.",
"required": [
"phoneNumber",
"type"
],
"type": "object",
"properties": {
"id": {
"description": "Id of this Phone. Does not need to be included when creating customer.",
"type": "string",
"example": "1"
},
"phoneNumber": {
"type": "string",
"example": 41783334444,
"nullable": false
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneType"
},
{
"description": "Type of this phone number. For company, only OFFICE type is supported",
"enum": [
"PRIVATE",
"OFFICE",
"MOBILE",
"WORK"
],
"example": "PRIVATE",
"nullable": false
}
]
}
}
},
"PhoneType": {
"enum": [
"PRIVATE",
"OFFICE",
"FAX",
"WORK",
"MOBILE"
],
"type": "string"
},
"PriceCategory": {
"description": "A price category effective in a price period.",
"type": "object",
"properties": {
"name": {
"description": "Name of the price category",
"type": "string"
},
"price": {
"description": "Effective price of this price category",
"pattern": "^\\d{1,19}([.]\\d{1,2})?$",
"type": "number"
}
}
},
"PricePeriod": {
"description": "A price period to apply for an article.",
"type": "object",
"properties": {
"validFrom": {
"format": "date",
"description": "The price period is valid from this time",
"type": "string"
},
"validTo": {
"format": "date",
"description": "The price period is invalid after this time",
"type": "string",
"readOnly": true
},
"price": {
"description": "The price used for an article within this price period",
"pattern": "^\\d{1,19}([.]\\d{1,2})?$",
"type": "number"
},
"priceCategories": {
"description": "List of price categories effective for this price period",
"type": "array",
"items": {
"$ref": "#/components/schemas/PriceCategory"
}
}
}
},
"PricePlan": {
"enum": [
"SINGLE",
"VOLUME",
"MONTHLY",
"QUARTERLY",
"YEARLY",
"FREE",
"PAY_PER_USE"
],
"type": "string"
},
"Product": {
"description": "A product in KLARA widget store. Enable different features for users.",
"required": [
"code",
"name"
],
"type": "object",
"properties": {
"code": {
"description": "Identifier code for each product-should be unique across all products",
"pattern": "\\S",
"type": "string",
"example": "PRINTANDSENT",
"nullable": false
},
"name": {
"description": "The name of the product",
"type": "string",
"example": "Print and sent"
}
}
},
"ProductType": {
"description": "Type of product used for an article",
"enum": [
"SERVICE",
"PRODUCTION",
"TRADE",
"OTHER",
"GIFT_CARD",
"PREPAYMENT"
],
"type": "string"
},
"PublicAPIToken": {
"description": "A public api token object. This object holds info of tokens that can be used to access KLARA Public API",
"type": "object",
"properties": {
"access_token": {
"description": "Token used to access KLARA Public API endpoints, should be place at Authorization header of request. Access token is valid only for one company tenant",
"type": "string"
},
"expires_in": {
"format": "int64",
"description": "Amount of time in seconds left that the access token is valid for",
"type": "integer"
},
"refresh_expires_in": {
"format": "int64",
"description": "Amount of time in seconds left that the refresh token is valid for",
"type": "integer"
},
"refreshToken": {
"description": "Token used to renew the access token",
"type": "string"
},
"token_type": {
"description": "Type of access token that should be included in the Authorziation header of each request",
"type": "string"
}
}
},
"PublicApiAccount": {
"description": "A master account from Klara's global chart of accounts.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal identifier of the master account.",
"type": "integer",
"example": 42
},
"code": {
"format": "int32",
"description": "Numeric account code as printed on the chart of accounts.",
"type": "integer",
"example": 1020
},
"name": {
"description": "Localized account name. Resolved against the request's Accept-Language and, when legal-form is supplied, against the legal-form-specific translation.",
"type": "string",
"example": "Bank"
},
"tags": {
"description": "Free-text keyword tokens associated with the account, used by client-side search. Tokens are delimited by comma or semicolon.",
"type": "string",
"example": "bank;konto"
},
"links": {
"description": "Linked-account references used by report computations.",
"type": "string",
"example": "bank_account"
},
"accountReportLinks": {
"description": "Report-grouping references used to assemble balance-sheet / P&L groupings.",
"type": "string",
"example": "bank_account"
},
"initialBalanceSheet": {
"description": "True when the account is part of the initial opening-balance sheet.",
"type": "boolean",
"example": false
},
"visibleFirstFiscalYear": {
"description": "True when the account is visible during the first fiscal year of a new company.",
"type": "boolean",
"example": true
},
"visibleFromSecondFiscalYear": {
"description": "True when the account becomes visible from the second fiscal year onwards.",
"type": "boolean",
"example": true
},
"vatAccount": {
"description": "True when the account is reserved for VAT postings.",
"type": "boolean",
"example": false
},
"accountReportFilters": {
"description": "Report-grouping configuration rows attached to this account.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiAccountReportFilter"
}
},
"notManuallyAdded": {
"description": "True when the account was seeded automatically (not added by an end user).",
"type": "boolean",
"example": true
}
}
},
"PublicApiAccountDisplaying": {
"description": "One account-displaying row for the manual-booking picker. Each row is a flat (account × optional sub-account) combination. When the account has no sub-account definitions, exactly one row is emitted with the link fields set to null. When the account has sub-account link specifications, one row is emitted per individual sub-account entry, numbered sequentially across all link types with a 0-based counter suffix.",
"type": "object",
"properties": {
"combinedCode": {
"description": "Picker key. \"<accountCode>-<i>\" when a sub-account exists (e.g. \"1020-0\"); the bare account code string (e.g. \"3000\") when linkType is null. The suffix index is a flat 0-based counter per account, spanning all link types in declaration order.",
"type": "string",
"example": "1020-0"
},
"combinedName": {
"description": "Picker label. \"<accountName> (<subAccountDisplay>)\" when a sub-account exists (e.g. \"Bank (UBS)\"); the bare account name (e.g. \"Bürobedarf\") when linkType is null.",
"type": "string",
"example": "Bank (UBS)"
},
"parentAccount": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiAccount"
},
{
"description": "The full master account this row belongs to. Identical across every row produced for the same account."
}
]
},
"linkType": {
"description": "Link-type category. Identifies the kind of entity the sub-account refers to. Common values: VAT_RATE, VAT_CASE, BANK, CUSTOMER, SUPPLIER, EMPLOYEE, SOCIAL_INSURANCE, TAX_AT_SOURCE, EQUITY, TANGIBLE_ASSET, IMMOBILE_TANGIBLE_ASSET, UNFINISHED_PRODUCTS, FINISHED_PRODUCTS, NON_BILLED_SERVICES, INVENTORY_CHANGE_MATERIAL, INVENTORY_CHANGE_GOODS, LONG_TERM_INTEREST_BEARING, OTHER_LONG_TERM_INTEREST_BEARING, GIFT_CARD, VARIOUS. null when the account has no sub-account definitions.",
"type": "string",
"example": "BANK"
},
"linkDisplay": {
"description": "Human-readable label for the link type in the requested Accept-Language. Falls back to the German label when no translation exists for the requested language. null when linkType is null.",
"type": "string",
"example": "Bank account"
},
"linkOptional": {
"description": "true when the sub-account selection is optional for the user (link keys are separated by ; in the account definition); false when selecting a sub-account is mandatory (link keys separated by ,); null when the account has no sub-account definitions.",
"type": "boolean",
"example": false
},
"specificationItem": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiFieldEntry"
},
{
"description": "The resolved sub-account entry for this row. null when the account has no sub-account definitions."
}
]
}
}
},
"PublicApiAccountReportFilter": {
"description": "Report-grouping configuration row attached to a master account.",
"type": "object",
"properties": {
"display": {
"description": "Human-readable label of the report bucket this account contributes to.",
"type": "string",
"example": "Operating expenses"
},
"linkAccountValue": {
"description": "Underlying linked-account value used by the accounting engine to resolve the bucket.",
"type": "string",
"example": "6000"
}
}
},
"PublicApiAccountingCompany": {
"description": "Accounting configuration of one company — dunning waiting periods plus the canonical company URI.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal id of the accounting-configuration row. Null when no configuration has been persisted yet for the company.",
"type": "integer",
"example": 17
},
"companyUri": {
"description": "Canonical compensation-side URI of the company, of the form /luz_compensation/api/{tenant}/companies/{companyId}.",
"type": "string",
"example": "/luz_compensation/api/c60d31fa-f335-4957-872a-90b035632081/companies/1"
},
"waitingDunningTime": {
"format": "int64",
"description": "Number of days to wait after the invoice due date before starting the dunning cycle. Defaults to 5 when no configuration exists yet.",
"type": "integer",
"example": 5
},
"dunningWaitingTimeLevelOne": {
"format": "int64",
"description": "Days to wait between the level-1 dunning notice and the level-2 escalation. Defaults to 10 when no configuration exists yet.",
"type": "integer",
"example": 10
},
"dunningWaitingTimeLevelTwo": {
"format": "int64",
"description": "Days to wait between the level-2 dunning notice and the level-3 escalation. Defaults to 10 when no configuration exists yet.",
"type": "integer",
"example": 10
},
"dunningWaitingTimeLevelThree": {
"format": "int64",
"description": "Days to wait between the level-3 dunning notice and the final escalation. Defaults to 10 when no configuration exists yet.",
"type": "integer",
"example": 10
}
}
},
"PublicApiArticleSetItem": {
"type": "object",
"properties": {
"id": {
"description": "Id of the article set",
"type": "string",
"example": "1"
},
"articleName": {
"description": "Article name of the article",
"type": "string",
"example": "Mobile phone"
},
"number": {
"description": "The number of the article",
"type": "string",
"example": "1"
},
"productType": {
"allOf": [
{
"$ref": "#/components/schemas/ProductType"
},
{
"description": "Product type of the article",
"example": "PRODUCTION"
}
]
},
"price": {
"description": "Price of the article",
"type": "number"
},
"vat": {
"allOf": [
{
"$ref": "#/components/schemas/ArticleVat"
},
{
"description": "Vat of the article"
}
]
},
"optionValues": {
"description": "Options for the set item if it is a variant",
"type": "array",
"items": {
"type": "string"
}
},
"href": {
"description": "Reference resource link",
"type": "string",
"example": "https://api.klara.ch/core/latest/articles/1"
}
}
},
"PublicApiBookingDetail": {
"description": "One debit or credit line of a booking.",
"required": [
"accountCode",
"crdrType",
"description",
"amount",
"tags",
"bookingTypeCode"
],
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal id of the booking detail. Assigned by the server on creation; omit when sending a new booking.",
"type": "integer",
"example": 1001
},
"accountCode": {
"format": "int32",
"description": "Ledger account number the amount is posted to (Swiss SME chart of accounts).",
"minimum": 1,
"type": "integer",
"example": 1020
},
"crdrType": {
"description": "Whether this line is a credit or a debit. Allowed values: CR, DR.",
"type": "string",
"example": "DR",
"nullable": false
},
"description": {
"description": "Free-text description shown on the journal report.",
"pattern": "\\S",
"type": "string",
"example": "Office supplies — invoice 2024-019",
"nullable": false
},
"amount": {
"description": "Absolute posting amount in the company main currency. Always positive; sign is carried by crdrType.",
"type": "number",
"example": 150,
"nullable": false
},
"partialPaymentAmount": {
"description": "Amount already paid against this line — only used for open-position bookings (invoices, credit notes).",
"type": "number",
"example": 0
},
"tags": {
"description": "Comma-separated list of string tags. Each tag is free-form and should represent a topic that the booking line should be associated with. Provide at least one tag per line.",
"type": "string",
"example": "project-alpha,q2",
"nullable": false
},
"links": {
"description": "Comma-separated list of structured links of entities that are considered the sub-accounts associated with an account code when making a booking line.This string can be empty when no sub-account is required for the current account code of the booking line.Each link has the format key:uri-path. Important: the exact URI values — including the tenant UUID and company ID segments — are returned verbatim by GET /core/v1/accounting/accounts/account-displaying in the account's specificationItem.link field; copy them as-is, do not construct them manually.bank_account — company bank account; URI from /luzfin_finance/api/{tenant}/companies/{cid}/bank-accounts/{id}cash — cash register; URI from /luz_accounting/api/{tenant}/companies/{cid}/cash/{id}transfer_account — transfer account; URI from /luz_accounting/api/{tenant}/companies/{cid}/transfer/{id}interest_bearing_current_account — interest-bearing current account; URI from /luz_accounting/api/{tenant}/companies/{cid}/interest-bearing-current/{id}non_interest_bearing_current_account — non-interest-bearing current account; URI from /luz_accounting/api/{tenant}/companies/{cid}/non-interest-bearing/{id}customer — accounts-receivable customer; URI from /luzfin_finance/api/{tenant}/companies/{cid}/customers/{id}supplier — accounts-payable supplier; URI from /luzfin_finance/api/{tenant}/companies/{cid}/customers/{id}employee — employee (payroll/HR); URI from /luz_compensation/api/{tenant}/companies/{cid}/employees/{id}vat_case — VAT case; URI from /luz_accounting/api/vat-cases/{id} (obtain from GET /core/latest/vat-cases)vat_rate — master VAT rate; URI from /luz_accounting/api/master-vats/{id} (obtain from GET /core/v1/accounting/master-vats)social_insurance — social insurance contract; URI from /luz_compensation/api/{tenant}/companies/{cid}/insurance-contracts/{id}tax_at_source — tax-at-source (withholding tax) state; URI from /luz_person/api/states/{id}financial_asset — financial asset; URI from /luz_accounting/api/{tenant}/companies/{cid}/financial-asset/{id}intangible_asset — intangible asset; URI from /luz_accounting/api/{tenant}/companies/{cid}/intangible-asset/{id}equity — equity account; URI from /luz_accounting/api/{tenant}/companies/{cid}/equity/{id}long_term_interest_bearing_liability — long-term loan; URI from /luz_accounting/api/{tenant}/companies/{cid}/long-term-interest-bearing/{id}statutory_profit_reserve — statutory profit reserve; URI from /luz_accounting/api/{tenant}/companies/{cid}/statutory-profit-reserve/{id}deferrals — accrual/deferral position; URI from /luz_accounting/api/{tenant}/companies/{cid}/deferral/{id}gift_card — gift card; URI from /luz_accounting/api/{tenant}/companies/{cid}/gift-cards/{id}not_billed_services — unbilled service position; URI from /luz_accounting/api/{tenant}/companies/{cid}/not-billed-services/{id}various — miscellaneous counterpart; URI from /luz_accounting/api/{tenant}/companies/{cid}/various/{id}inventory_change_goods — inventory type (static); URI: /luz_accounting/api/inventory-types/inventory-change-goodsinventory_change_material — inventory type (static); URI: /luz_accounting/api/inventory-types/inventory-change-materialnon_billed_services — inventory type (static); URI: /luz_accounting/api/inventory-types/non-billed-servicesfinished_products — inventory type (static); URI: /luz_accounting/api/inventory-types/finished-productsunfinished_products — inventory type (static); URI: /luz_accounting/api/inventory-types/unfinished-productsautoCalculateVat=true: the account the automatically generated VAT counterpart line is posted to (the GUI \"VAT account\", e.g. 1170). Required on a VAT-bearing line when the line carries a vat_rate link and omits its own VAT line. Ignored when autoCalculateVat is false (caller pre-splits the lines).",
"type": "integer",
"example": 1170
},
"vatTypeDescription": {
"description": "How VAT is recorded for this line. Allowed values: INCLUSIVE, EXCLUSIVE, NONE.",
"type": "string",
"example": "INCLUSIVE"
},
"vatBookingDetailLink": {
"description": "URI of the companion VAT booking detail, when one was generated automatically.",
"type": "string"
},
"vatAmount": {
"description": "VAT amount carried on this line, in the company main currency.",
"type": "number",
"example": 11.4
},
"vatRate": {
"description": "Effective VAT rate (percent) applied to this line.",
"type": "number",
"example": 7.7
},
"vatRateDisplay": {
"description": "Display string of the VAT rate as rendered in the UI.",
"type": "string",
"example": "7.7%"
},
"vatBookingDetail": {
"description": "True when this line is the automatically generated VAT counterpart of another line.",
"type": "boolean",
"example": false
},
"bookingTypeCode": {
"description": "Business meaning of the booking line. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.",
"type": "string",
"example": "GENERAL_LEDGER",
"nullable": false
},
"openPositionStatus": {
"description": "Lifecycle of the open position represented by this line. Allowed values include OPEN, PARTIALLY_PAID, PAID, CLOSED.",
"type": "string",
"example": "OPEN"
},
"creditorReference": {
"description": "Creditor reference (QR-bill / ISO 11649) attached to the open position.",
"type": "string"
},
"isrReference": {
"description": "ISR reference number attached to the open position.",
"type": "string"
},
"isrMember": {
"description": "ISR participant (member) number of the creditor.",
"type": "string"
},
"partnerIban": {
"description": "IBAN of the counterpart used for outgoing payments.",
"type": "string"
},
"endToEndId": {
"description": "Pain.001 end-to-end id, propagated to the outgoing payment instruction.",
"type": "string"
},
"isExcludeVatAmount": {
"description": "When true, the gross amount on this line excludes VAT; otherwise it includes VAT.",
"type": "boolean",
"example": false
},
"foreignCurrencyAmount": {
"description": "Posting amount in the foreign currency, when the line is booked in a non-main currency.",
"type": "number"
},
"foreignCurrencyUnit": {
"description": "ISO 4217 code of the foreign currency.",
"type": "string",
"example": "EUR"
},
"paidDate": {
"format": "date-time",
"description": "Date on which the open position was settled (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2024-06-15T00:00:00Z"
},
"dueDate": {
"format": "date-time",
"description": "Date on which the open position becomes overdue (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2024-06-30T00:00:00Z"
},
"paymentDate": {
"format": "date-time",
"description": "Date on which the payment instruction is scheduled (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2024-06-28T00:00:00Z"
},
"servicePeriodFrom": {
"format": "date-time",
"description": "Start of the service period covered by the line (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2024-06-01T00:00:00Z"
},
"servicePeriodTo": {
"format": "date-time",
"description": "End of the service period covered by the line (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2024-06-30T00:00:00Z"
},
"paymentPercentage": {
"description": "Percentage of the open-position amount already settled.",
"type": "number",
"example": 0
},
"isDunningBlocked": {
"description": "When true, dunning reminders are suppressed for this open position.",
"type": "boolean",
"example": false
}
}
},
"PublicApiBookingHeader": {
"description": "A booking (manual journal entry) together with its debit/credit lines.",
"required": [
"documentDate",
"bookingDate",
"bookingDetails"
],
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal id of the booking. Assigned by the server on creation; omit when sending a new booking.",
"type": "integer",
"example": 12345
},
"companyId": {
"format": "int64",
"description": "Internal id of the company this booking belongs to. Filled by the server from the caller's session; ignored on input.",
"type": "integer",
"example": 1
},
"documentDate": {
"format": "date-time",
"description": "Date printed on the underlying document, e.g. supplier invoice date (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2024-06-15T00:00:00Z"
},
"bookingDate": {
"format": "date-time",
"description": "Effective accounting date of the booking; must fall inside an open fiscal year unless confirmDontMindClosingFiscalYear is set (yyyy-MM-ddT00:00:00Z).",
"type": "string",
"example": "2024-06-15T00:00:00Z",
"nullable": false
},
"documentIds": {
"description": "Ids of supporting documents (uploaded files / e-mails) attached to this booking.",
"type": "array",
"items": {
"type": "string"
}
},
"businessCase": {
"description": "Free-text business case label shown on the journal.",
"type": "string",
"example": "Office supplies"
},
"snippets": {
"description": "Snippet identifiers applied to this booking, copied from the booking template.",
"type": "array",
"items": {
"type": "string"
}
},
"bookingStatus": {
"description": "Status of the booking. Allowed values: DRAFT, BOOKED, CANCELLED.",
"type": "string",
"example": "BOOKED"
},
"internalComment": {
"description": "Internal comment, visible only to accounting users.",
"type": "string"
},
"businessCaseId": {
"description": "Reference to the business-case document (workflow id) that produced this booking, when applicable.",
"type": "string"
},
"relatedBookingHeaderLinks": {
"description": "URIs of bookings that are related to this one (e.g. payment ↔ invoice, original ↔ delimitation).",
"type": "array",
"items": {
"type": "string"
}
},
"bookingDetails": {
"description": "Debit and credit lines of the booking. Must contain at least two lines whose debit and credit totals balance.",
"minItems": 2,
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiBookingDetail"
},
"nullable": false
},
"invoiceNumber": {
"description": "Invoice number printed on the document.",
"type": "string",
"example": "2024-019"
},
"orderManagementInvoiceLink": {
"description": "Klara order-management invoice URI when the booking was generated from a Klara invoice.",
"type": "string"
},
"bookingTemplateId": {
"format": "int64",
"description": "Id of the booking template the user picked when creating this entry.",
"type": "integer",
"example": 501
},
"bookingTitle": {
"description": "Short title of the booking shown in lists.",
"type": "string",
"example": "Office supplies — June 2024"
},
"totalAmount": {
"description": "Sum of the absolute amounts of the booking lines, in the company main currency.",
"type": "number",
"example": 150
},
"bookingTypeCode": {
"description": "Business meaning of the booking. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.",
"type": "string",
"example": "GENERAL_LEDGER"
}
}
},
"PublicApiBookingType": {
"description": "A master booking type from Klara's global accounting catalog.",
"type": "object",
"properties": {
"code": {
"description": "Stable machine-readable code of the booking type.",
"enum": [
"GENERAL_LEDGER",
"AP_INVOICE",
"AP_PAYMENT",
"AR_INVOICE",
"AR_PAYMENT",
"AP_PREPAYMENT",
"AP_PREPAYUSE",
"AR_PREPAYMENT",
"AR_PREPAYUSE",
"AR_CREDITNOTE",
"AR_CREDITUSE",
"AP_CREDITNOTE",
"AP_CREDITUSE",
"AMORTIZATION",
"SELLOFF_AMORTIZATION",
"DELIMIT"
],
"type": "object",
"example": "AP_INVOICE"
},
"description": {
"description": "Localized human-readable description of the booking type. Resolved against the request's Accept-Language header; falls back to the German translation when no translation exists for the requested language.",
"type": "string",
"example": "Kreditorenrechnung"
}
}
},
"PublicApiBusinessCase": {
"description": "Hydrated business-case aggregate: template, dates the company-VAT and fiscal year resolve to, and the snippet / field tree used by the booking form.",
"type": "object",
"properties": {
"businessCaseId": {
"format": "int64",
"description": "Identifier of the business case instance when persisted; null on a freshly hydrated template.",
"type": "integer",
"example": "null"
},
"businessCaseTemplateId": {
"format": "int64",
"description": "Identifier of the business-case template this aggregate was hydrated from.",
"type": "integer",
"example": 101
},
"documentId": {
"description": "Identifier of the underlying document the business case is attached to; null when the booking is not yet linked to a document.",
"type": "string",
"example": "null"
},
"display": {
"description": "Pre-translated display label of the business-case template for the request's Accept-Language.",
"type": "string",
"example": "Bürobedarf"
},
"bookingNumbers": {
"description": "Comma-separated list of booking numbers already generated for this business case; empty on a fresh template.",
"type": "string",
"example": ""
},
"effectiveCompanyVatDate": {
"format": "date",
"description": "Date used to resolve the company-VAT regime applicable to this business case (ISO yyyy-MM-dd).",
"type": "string",
"example": "2024-06-15"
},
"documentDate": {
"format": "date",
"description": "Document date associated with the business case (ISO yyyy-MM-dd).",
"type": "string",
"example": "2024-06-15"
},
"effectiveFiscalYearDate": {
"format": "date",
"description": "Date used to resolve the fiscal year applicable to this business case (ISO yyyy-MM-dd).",
"type": "string",
"example": "2024-06-15"
},
"fiscalYearHasCreatedAuto": {
"description": "True when the downstream service had to auto-create the fiscal year covering the resolved date.",
"type": "boolean",
"example": false
},
"withOP": {
"description": "True when this business case is tracked as an open item (OP). May be null when not applicable.",
"type": "boolean",
"example": false
},
"fields": {
"description": "Recursive snippet-and-field tree driving the booking form, keyed by snippet code. The shape of each entry follows the downstream BusinessCaseField model (see analysis report §8.2).",
"type": "object",
"additionalProperties": {
"type": "object"
},
"example": {
"PAYMENT": {
"snippetId": 42,
"nestedFields": {}
}
}
},
"entriesDefinition": {
"description": "Per-field entries definitions used by the booking form to resolve enum-like fields. Each entry mirrors the downstream FieldEntriesDefinition model (see analysis report §8.2).",
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
},
"PublicApiBusinessCasePeriod": {
"description": "A financial-year period and the business-case templates valid for the company within it.",
"type": "object",
"properties": {
"companyId": {
"format": "int64",
"description": "Internal id of the company this period belongs to.",
"type": "integer",
"example": 1
},
"periodFrom": {
"format": "date",
"description": "Inclusive start date of the financial year (ISO yyyy-MM-dd).",
"type": "string",
"example": "2024-01-01"
},
"periodTo": {
"format": "date",
"description": "Inclusive end date of the financial year (ISO yyyy-MM-dd).",
"type": "string",
"example": "2024-12-31"
},
"legalForm": {
"description": "Legal form of the company during this period. Allowed values include EINZEL, GMBH, AG, KOLLEKTIV, KOMMANDIT, GENOSSENSCHAFT, VEREIN, STIFTUNG.",
"type": "string",
"example": "EINZEL"
},
"companyVat": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiCompanyVatType"
},
{
"description": "VAT regime active during this period."
}
]
},
"status": {
"description": "Status of the fiscal year. Allowed values: OPEN, CLOSING, CLOSED.",
"type": "string",
"example": "OPEN"
},
"businessCaseTemplates": {
"description": "Business-case templates valid for the company's legal form and VAT regime within this period, sorted by code.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiBusinessCaseTemplate"
}
}
}
},
"PublicApiBusinessCaseTemplate": {
"description": "A manual-journal category usable for bookings, with its catalogue code and translations.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal id of the template in the Klara catalogue.",
"type": "integer",
"example": 101
},
"code": {
"description": "Stable catalogue code of the template.",
"type": "string",
"example": "OFFICE_SUPPLIES"
},
"display": {
"description": "Label of the template, already translated for the request's Accept-Language.",
"type": "string",
"example": "Bürobedarf"
},
"i18n": {
"description": "All translations of the label, keyed by IETF language tag.",
"type": "object",
"additionalProperties": {
"type": "string"
},
"example": {
"de": "Bürobedarf",
"fr": "Fournitures de bureau"
}
},
"keywordI18ns": {
"description": "All translations of the search keywords, keyed by IETF language tag.",
"type": "object",
"additionalProperties": {
"type": "string"
},
"example": {
"de": "Büro Material",
"fr": "Fournitures"
}
},
"group": {
"description": "Catalogue group the template belongs to.",
"type": "string",
"example": "Operating expenses"
}
}
},
"PublicApiCompanyVatType": {
"description": "VAT regime of a company within a fiscal period.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal id of the company VAT row.",
"type": "integer",
"example": 42
},
"reportingVat": {
"description": "Reporting method used to declare VAT. Allowed values: EFFECTIVE, NET_TAX_RATE, FLAT_TAX_RATE.",
"type": "string",
"example": "EFFECTIVE"
},
"billing": {
"description": "Billing method used to determine VAT liability. Allowed values: AGREED, RECEIVED.",
"type": "string",
"example": "AGREED"
},
"code": {
"description": "Composite VAT code combining reporting method and billing, or NON_VAT when the company is not VAT-liable.",
"type": "string",
"example": "EFFECTIVE_AGREED"
},
"hasVat": {
"description": "True when the company is VAT-liable in this period.",
"type": "boolean",
"example": true
},
"validFrom": {
"format": "date",
"description": "Inclusive start date of the VAT regime (ISO yyyy-MM-dd).",
"type": "string",
"example": "2024-01-01"
},
"validTo": {
"format": "date",
"description": "Inclusive end date of the VAT regime (ISO yyyy-MM-dd).",
"type": "string",
"example": "2024-12-31"
},
"yearlySettlement": {
"description": "True for yearly VAT settlement, false for quarterly/semi-annual.",
"type": "boolean",
"example": false
}
}
},
"PublicApiCrDrType": {
"enum": [
"CR",
"DR"
],
"type": "string"
},
"PublicApiEmployeeShortInfo": {
"description": "Lightweight employee entry (identity, contact and workplace) for directory/lookup listings.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Employee id. Use this as employeeId in employee-scoped endpoints.",
"type": "integer",
"example": 3487
},
"firstName": {
"description": "Employee's first name (resolved from the person record).",
"type": "string",
"example": "Anna"
},
"lastName": {
"description": "Employee's last name (resolved from the person record).",
"type": "string",
"example": "Müller"
},
"employeeNumber": {
"description": "Company-assigned employee number.",
"type": "string",
"example": "E-00123"
},
"email": {
"description": "Employee's primary email (resolved from the person record).",
"type": "string",
"example": "anna.mueller@example.com"
},
"workplaceId": {
"format": "int64",
"description": "Id of the workplace of the employee's current contract.",
"type": "integer",
"example": 12
},
"personnelNumber": {
"description": "Personnel number of the employee.",
"type": "string",
"example": "P-4711"
},
"numberOfChildren": {
"format": "int64",
"description": "Number of children registered for the employee.",
"type": "integer",
"example": 2
},
"cashPayment": {
"description": "Whether the employee is paid in cash.",
"type": "boolean",
"example": false
},
"status": {
"description": "Contract status of the employee. Allowed values: ACTIVE, INACTIVE, DRAFT.",
"type": "string",
"example": "ACTIVE"
}
}
},
"PublicApiFailArticle": {
"description": "Contain error information and data of unsaved article",
"type": "object",
"properties": {
"errorCode": {
"description": "Error code",
"type": "string",
"example": "article.number.could.not.be.duplicated"
},
"errorMessage": {
"description": "Error message",
"type": "string",
"example": "Article number could not be duplicated"
},
"unsavedArticle": {
"allOf": [
{
"$ref": "#/components/schemas/Article"
},
{
"description": "Article data which could not be saved"
}
]
}
}
},
"PublicApiFieldEntry": {
"description": "One concrete sub-account choice; carries the URI to round-trip to the booking endpoint and the display label.",
"type": "object",
"properties": {
"id": {
"description": "Stable identifier of the underlying entity (e.g. bank-account id, VAT-rate id, customer id). May be null for synthesized entries.",
"type": "string",
"example": "42"
},
"filteredBy": {
"description": "Optional filter token used by the Accounting UI to narrow the picker. Empty for most link types.",
"type": "string",
"example": ""
},
"display": {
"description": "Human-readable label shown in the picker (e.g. \"UBS\" for a bank account, \"8.1 %\" for a VAT rate).",
"type": "string",
"example": "UBS"
},
"link": {
"description": "Canonical URI for this sub-account choice. MUST be round-tripped verbatim to the booking-creation endpoint when the row is selected.",
"type": "string",
"example": "bank_account:/luz_finance/api/5fe76717-60a0-4b20-9819-255a957f3eb9/companies/1/bank-accounts/42"
},
"additionalAttribute": {
"description": "Free-form additional attribute attached by the link-type supplier. Most types leave this empty.",
"type": "string",
"example": ""
},
"snippetReference": {
"description": "Optional snippet reference returned by the underlying entity (used by some link types to carry a template hint).",
"type": "string",
"example": ""
},
"value": {
"description": "Optional raw value associated with the entry (e.g. the VAT percentage as a decimal string).",
"type": "string",
"example": "8.1"
},
"validFrom": {
"format": "date",
"description": "Inclusive start of the validity window of the underlying entity (ISO yyyy-MM-dd). null when not applicable.",
"type": "string",
"example": "2024-01-01"
},
"validTo": {
"format": "date",
"description": "Inclusive end of the validity window of the underlying entity (ISO yyyy-MM-dd). null when open-ended.",
"type": "string",
"example": "2024-12-31"
}
}
},
"PublicApiMasterVat": {
"description": "Global master VAT row: code, rate, validity range and translated labels.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal id of the master VAT row.",
"type": "integer",
"example": 12
},
"vatCode": {
"description": "Short numeric VAT code as configured in the Klara accounting plan.",
"type": "string",
"example": "1"
},
"rate": {
"description": "VAT rate as a percentage value (8.10 means 8.10 %).",
"type": "number",
"example": 8.1
},
"validFrom": {
"format": "date",
"description": "Inclusive start date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.",
"type": "string",
"example": "2024-01-01"
},
"validTo": {
"format": "date",
"description": "Inclusive end date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.",
"type": "string",
"example": "2030-12-31"
},
"defaultVat": {
"description": "True when the row is one of the company-default VAT entries.",
"type": "boolean",
"example": true
},
"masterVatMulties": {
"description": "Localized labels keyed by language tag.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiMasterVatMulti"
}
},
"referenceVatCaseId": {
"description": "Optional reference to a hidden VAT case id not directly mapped to a master VAT.",
"type": "string",
"example": "VC-7"
},
"createDate": {
"format": "date-time",
"description": "Timestamp when the row was created (ISO yyyy-MM-dd'T'HH:mm:ss).",
"type": "string",
"example": "2024-01-01T08:00:00"
},
"updateDate": {
"format": "date-time",
"description": "Timestamp of the last update (ISO yyyy-MM-dd'T'HH:mm:ss).",
"type": "string",
"example": "2024-06-15T14:30:00"
}
}
},
"PublicApiMasterVatMulti": {
"description": "Translated label of a master VAT row.",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Internal id of the translation row.",
"type": "integer",
"example": 101
},
"language": {
"description": "Language tag of the translation (ISO 639-1).",
"type": "string",
"example": "de"
},
"description": {
"description": "Human-readable VAT description in the matching language.",
"type": "string",
"example": "Normalsatz 8.1 %"
}
}
},
"PublicApiSuitableOpenPosition": {
"description": "An accounting open-position booking detail line returned by the bank-reconciliation suggestion service. Carries the canonical booking-detail fields plus reconciliation-specific enrichments (partner-name display, business-case message id, computed open amount).",
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "Booking-detail row id (database primary key).",
"type": "integer",
"example": 98765
},
"bookingHeaderId": {
"format": "int64",
"description": "Id of the booking header this detail belongs to.",
"type": "integer",
"example": 4321
},
"bookingHeaderComment": {
"description": "Free-text comment of the booking header.",
"type": "string",
"example": "Invoice 2026-0123 from Migros AG"
},
"businessCaseId": {
"format": "int64",
"description": "Id of the parent business case.",
"type": "integer",
"example": 12345
},
"accountCode": {
"description": "Numeric account code on which the booking is posted.",
"type": "string",
"example": "1100"
},
"accountLinkDisplay": {
"description": "Localized account label.",
"type": "string",
"example": "Forderungen aus L+L"
},
"crdrType": {
"description": "Credit / debit indicator.",
"enum": [
"CR",
"DR"
],
"type": "object",
"example": "DR"
},
"description": {
"description": "Free-text description of the booking line.",
"type": "string",
"example": "Rechnung Nr. 2026-0123"
},
"bookingTypeCode": {
"description": "Stable booking-type code of the underlying business case.",
"enum": [
"GENERAL_LEDGER",
"AP_INVOICE",
"AP_PAYMENT",
"AR_INVOICE",
"AR_PAYMENT",
"AP_PREPAYMENT",
"AP_PREPAYUSE",
"AR_PREPAYMENT",
"AR_PREPAYUSE",
"AR_CREDITNOTE",
"AR_CREDITUSE",
"AP_CREDITNOTE",
"AP_CREDITUSE",
"AMORTIZATION",
"SELLOFF_AMORTIZATION",
"DELIMIT"
],
"type": "object",
"example": "AR_INVOICE"
},
"openPositionStatus": {
"description": "Open-position lifecycle status.",
"enum": [
"OPEN",
"PARTLY_PAID",
"PAID",
"PARTLY_CLEARED",
"CLEARED"
],
"type": "object",
"example": "OPEN"
},
"amount": {
"description": "Gross posted amount of the booking line.",
"type": "number",
"example": 1250
},
"partialPaymentAmount": {
"description": "Sum of payments / clearings already applied to this position.",
"type": "number",
"example": 0
},
"openAmount": {
"description": "Computed remaining amount still to be cleared (amount - partialPaymentAmount).",
"type": "number",
"example": 1250
},
"vatAmount": {
"description": "VAT amount included in the gross posting.",
"type": "number",
"example": 94.05
},
"vatRate": {
"description": "VAT rate applied to the line as a decimal (e.g. 0.077).",
"type": "number",
"example": 0.081
},
"vatRateDisplay": {
"description": "Localized VAT-rate display string.",
"type": "string",
"example": "8.1 %"
},
"vatBookingDetailLink": {
"description": "Self-link of the companion VAT booking-detail line, when present.",
"type": "string"
},
"vatBookingDetail": {
"description": "Whether this row is itself a derived VAT booking-detail line.",
"type": "boolean",
"example": false
},
"foreignCurrencyAmount": {
"description": "Posted amount in the document's foreign currency, when applicable.",
"type": "number",
"example": 1250
},
"foreignCurrencyUnit": {
"description": "ISO-4217 currency code of foreignCurrencyAmount.",
"type": "string",
"example": "EUR"
},
"tags": {
"description": "Free-form tag string attached to the booking line.",
"type": "string",
"example": "test manual"
},
"documentDate": {
"format": "date",
"description": "Document (invoice) date of the underlying business case.",
"type": "string",
"example": "2026-04-15"
},
"bookingDate": {
"format": "date",
"description": "Date the booking was journaled.",
"type": "string",
"example": "2026-04-15"
},
"paidDate": {
"format": "date",
"description": "Date the position was last (partially) paid, if any.",
"type": "string",
"example": "2026-05-10"
},
"dueDate": {
"format": "date",
"description": "Due date for payment.",
"type": "string",
"example": "2026-05-15"
},
"paymentDate": {
"format": "date",
"description": "Effective payment date of the booking line.",
"type": "string",
"example": "2026-05-12"
},
"servicePeriodFrom": {
"format": "date",
"description": "Inclusive lower bound of the service period this booking covers.",
"type": "string",
"example": "2026-04-01"
},
"servicePeriodTo": {
"format": "date",
"description": "Inclusive upper bound of the service period this booking covers.",
"type": "string",
"example": "2026-04-30"
},
"createDate": {
"format": "date-time",
"description": "Timestamp at which the booking detail was created.",
"type": "string",
"example": "2026-04-15T08:30:00"
},
"updateDate": {
"format": "date-time",
"description": "Timestamp at which the booking detail was last updated.",
"type": "string",
"example": "2026-05-12T14:15:00"
},
"documentId": {
"description": "List of document ids attached to the booking line.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"1771764"
]
},
"partnerName": {
"description": "Resolved partner display name for the position.",
"type": "string",
"example": "Migros AG"
},
"bookingDetailUri": {
"description": "Stable URI of the booking-detail row, for cross-service linking.",
"type": "string",
"example": "/api/luz_accounting/api/{tenantId}/companies/{companyId}/booking-headers/4321/booking-details/98765"
},
"orderManagementInvoiceLink": {
"description": "Self-link of the linked order-management invoice, when applicable.",
"type": "string"
},
"orderManagementInvoiceNumber": {
"description": "Resolved order-management invoice number for display.",
"type": "string",
"example": "INV-2026-0123"
},
"msgId": {
"description": "Business-case message id, used by the eletter / inbox subsystems.",
"type": "string",
"example": "MSG-7788"
},
"creditorReference": {
"description": "Creditor reference (Swiss QR-IBAN reference number) of the position.",
"type": "string"
},
"isrReference": {
"description": "ISR reference of the position, when applicable.",
"type": "string"
},
"isrMember": {
"description": "ISR member number, when applicable.",
"type": "string"
},
"partnerIban": {
"description": "IBAN of the partner / counterparty.",
"type": "string"
},
"endToEndId": {
"description": "End-to-end identifier carried on the bank transaction.",
"type": "string"
}
}
},
"PublicApiVatProfile": {
"description": "The company's VAT reporting profile.",
"type": "object",
"properties": {
"hasVat": {
"description": "Whether the company is VAT-registered.",
"type": "boolean",
"example": true
},
"reportingMode": {
"description": "VAT regime. EFFECTIVE_CLEARING or REPORTING_USING_NET_TAX_RATES.",
"type": "string",
"example": "EFFECTIVE_CLEARING"
},
"billing": {
"description": "Billing method. BILLED or COLLECTED.",
"type": "string",
"example": "BILLED"
},
"sss1": {
"description": "Flat net-tax rate 1 (percent), when reporting under net tax rates.",
"type": "number",
"example": 1
},
"sss2": {
"description": "Flat net-tax rate 2 (percent), when reporting under net tax rates.",
"type": "number",
"example": 0.5
}
}
},
"PublicApiVatSuggestion": {
"description": "A ready-to-use VAT case/rate/account bundle.",
"type": "object",
"properties": {
"label": {
"description": "Human-meaningful label. Use it as the option text in the VAT-rate dropdown.",
"type": "string",
"example": "Domestic purchase — 8.1%"
},
"recommended": {
"description": "True on the server's recommended default bundle — preselect this row in the dropdowns.",
"type": "boolean",
"example": true
},
"reason": {
"description": "Why this bundle is suggested.",
"type": "string",
"example": "Default VAT rate for DOMESTIC_PURCHASE."
},
"vatCaseCode": {
"description": "VAT case code. Group rows by this value to build the VAT-case dropdown.",
"type": "string",
"example": "DOMESTIC_PURCHASE"
},
"vatCaseLink": {
"description": "Verbatim link to copy into a booking line's links (comma-joined with vatRateLink).",
"type": "string",
"example": "vat_case:/luz_accounting/api/vat-cases/1"
},
"vatRateDisplay": {
"description": "Display string of the VAT rate — the VAT-rate dropdown option within the selected VAT case.",
"type": "string",
"example": "8.1%"
},
"vatRateLink": {
"description": "Verbatim link to copy into a booking line's links (comma-joined with vatCaseLink).",
"type": "string",
"example": "vat_rate:/luz_accounting/api/master-vats/59"
},
"vatAccountCode": {
"format": "int32",
"description": "Suggested VAT account for the generated VAT line — preselect this in the VAT-account dropdown; the first of vatAccountCodes (confirm against your chart of accounts).",
"type": "integer",
"example": 1170
},
"vatAccountCodes": {
"description": "All VAT accounts the company's chart maps to this account + VAT case; the options for the GUI's VAT-account dropdown.",
"type": "array",
"items": {
"format": "int32",
"type": "integer"
},
"example": [
1170,
1171
]
},
"previewNet": {
"description": "Net amount preview — the Debit/Credit preview shown in the GUI. Null until an amount is supplied; refreshes when amount/amountKind change.",
"type": "number",
"example": 925.93
},
"previewVat": {
"description": "VAT amount preview — the VAT portion shown in the GUI. Null until an amount is supplied; refreshes when amount/amountKind change.",
"type": "number",
"example": 74.07
}
}
},
"PublicApiVatType": {
"description": "A VAT-type row from Klara's global VAT-type catalogue.",
"type": "object",
"properties": {
"vatTypeCode": {
"description": "Klara VAT-type code that identifies the row.",
"type": "string",
"example": "M81"
},
"companyType": {
"description": "Company-type bucket the VAT type applies to.",
"type": "string",
"example": "LIMITED_LIABILITY"
},
"description": {
"description": "Localized description, resolved against the request Accept-Language header (German fallback).",
"type": "string",
"example": "Vorsteuer Material- und Dienstleistungsaufwand"
},
"vatTypeShortName": {
"description": "Localized short name, resolved against the request Accept-Language header (German fallback).",
"type": "string",
"example": "VSt MA"
},
"i18n": {
"description": "Raw description translations keyed by lowercase IETF language tag. Useful when a client renders its own language picker; otherwise prefer the resolved description field.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"i18nShortName": {
"description": "Raw short-name translations keyed by lowercase IETF language tag.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"vatTypeFormula": {
"description": "Posting formulas attached to this VAT type, one per associated VAT case.",
"uniqueItems": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiVatTypeFormula"
}
}
}
},
"PublicApiVatTypeFormula": {
"description": "Posting formula attached to a Klara VAT type.",
"type": "object",
"properties": {
"vatCaseCode": {
"description": "Linked VAT-case code this formula belongs to.",
"type": "string",
"example": "VAT_RECEIVABLE"
},
"vatTypeCode": {
"description": "VAT-type code this formula belongs to.",
"type": "string",
"example": "M81"
},
"companyType": {
"description": "Company-type bucket the formula applies to.",
"type": "string",
"example": "LIMITED_LIABILITY"
},
"account": {
"description": "Account number on which the VAT entry is booked.",
"type": "string",
"example": "2200"
},
"contraAccount": {
"description": "Contra-account number for the VAT entry.",
"type": "string",
"example": "1170"
},
"linkedBookingAccount": {
"description": "Linked auxiliary account, when applicable.",
"type": "string",
"example": "2201"
},
"specialRatesType": {
"description": "Special-rates flag (enum name from the upstream model). Surfaced as a string so future internal enum additions stay backwards compatible.",
"type": "string",
"example": "STANDARD"
},
"value": {
"description": "Formula value flag (enum name from the upstream model). Surfaced as a string for forward compatibility.",
"type": "string",
"example": "NORMAL"
}
}
},
"RepresentationLinks": {
"description": "links metadata",
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/Link"
}
}
},
"Salutation": {
"enum": [
"MALE",
"FEMALE",
"MALE_FEMALE",
"FAMILY"
],
"type": "string"
},
"SendInvoiceResult": {
"description": "Result of sending a single, already-booked invoice. Reports whether the invoice was delivered, whether the channel was auto-selected (smart delivery), the channel actually used, the OneAPI delivery id and the archived PDF's printedFileId.",
"type": "object",
"properties": {
"delivered": {
"description": "true when delivery was confirmed via the channel actually used.",
"type": "boolean",
"example": true
},
"smart": {
"description": "true when the channel was auto-selected (smart delivery, i.e. no channel was forced); false when a channel was forced.",
"type": "boolean",
"example": true
},
"channel": {
"description": "The channel actually used to deliver the invoice. For physical post this is the resolved postage method (e.g. A_POST).",
"enum": [
"A_POST",
"B_POST",
"SEND_EMAIL",
"PRINT_AND_MANUAL_SEND",
"EPOST",
"EBILL"
],
"type": "object",
"example": "SEND_EMAIL"
},
"deliveryId": {
"description": "OneAPI delivery id, when available (forced sends only; null for smart delivery).",
"type": "string",
"example": "9b1f4c8e-2d3a-4f6b-8c7d-1e2f3a4b5c6d"
},
"printedFileId": {
"description": "The printedFileId of the archived invoice PDF rendered/reused during the send.",
"type": "string",
"example": "1771764"
}
}
},
"ShippingInfo": {
"description": "shipping information for an article.",
"type": "object",
"properties": {
"shippingAttributes": {
"description": "List of attributes used for shipping",
"type": "array",
"items": {
"type": "string"
}
},
"weightUnit": {
"$ref": "#/components/schemas/WeightUnit"
},
"dimensionUnit": {
"$ref": "#/components/schemas/DimensionUnit"
},
"weight": {
"description": "Weight of this article",
"pattern": "^\\d{1,19}([.]\\d{1,2})?$",
"type": "number"
},
"width": {
"description": "Width of this article",
"pattern": "^\\d{1,19}([.]\\d{1,2})?$",
"type": "number"
},
"height": {
"description": "Height of this article",
"pattern": "^\\d{1,19}([.]\\d{1,2})?$",
"type": "number"
},
"depth": {
"description": "Depth of this article",
"pattern": "^\\d{1,19}([.]\\d{1,2})?$",
"type": "number"
}
}
},
"SortDirection": {
"description": "Sort direction. Allowed values: ASC, DESC.",
"enum": [
"ASC",
"DESC"
],
"type": "string"
},
"State": {
"description": "A partner State.",
"type": "object",
"properties": {
"id": {
"type": "string",
"readOnly": true
},
"code": {
"description": "Code of this State",
"type": "string",
"example": "VD"
},
"description": {
"description": "Extended description of this State",
"type": "string",
"example": "Vaud"
}
}
},
"Subscription": {
"description": "Subscription for a product in KLARA. Enable different features for users.",
"required": [
"product",
"marketingCodes"
],
"type": "object",
"properties": {
"product": {
"allOf": [
{
"$ref": "#/components/schemas/Product"
},
{
"description": "The product to be subscribed. Identifier code for each product-should be unique across all products.",
"nullable": false
}
]
},
"marketingCodes": {
"description": "Marketing code to identify which product will be subscribed.",
"type": "array",
"items": {
"type": "string"
},
"example": "K-01-0002-00-M, K-02-0005-00-Y",
"nullable": false
},
"pricePlan": {
"allOf": [
{
"$ref": "#/components/schemas/PricePlan"
},
{
"description": "Specify how the subscription is paid.