{"openapi":"3.1.0","info":{"title":"Accounting API","version":"1.0.0","description":"REST API exposing the actions of the Accounting product. Authenticate with a Kavaro API key as a bearer token."},"servers":[{"url":"https://kavaro.ai"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"A Kavaro API key (user- or organization-scoped)."}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/rest/actions/capture_document":{"post":{"operationId":"capture_document","summary":"Capture document","description":"Register a captured receipt or supplier invoice (an uploaded file and/or its text) so it can be extracted, coded and posted.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"fileId":{"description":"The id of an already-uploaded ProductFile holding the receipt/invoice bytes","type":"string"},"fileName":{"description":"Display file name","type":"string"},"mimeType":{"description":"MIME type of the uploaded file","type":"string"},"text":{"description":"Raw text of the document (e.g. an email body), when there is no file to OCR","type":"string"},"source":{"description":"How the document arrived; defaults to upload","type":"string","enum":["upload","email","webhook"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/extract_document":{"post":{"operationId":"extract_document","summary":"Extract document","description":"Run AI extraction on a captured document to read out supplier, date, total, VAT and currency. Moves it from draft to extracted.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"The document to extract"}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/code_document":{"post":{"operationId":"code_document","summary":"Code document","description":"Apply the organization's region rules to map an extracted document to a ledger account / category and VAT code. Moves it from extracted to coded.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"The document to code"}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/update_coding":{"post":{"operationId":"update_coding","summary":"Update coding","description":"Correct the proposed coding of a document (ledger account, category, VAT code, booking text or amount) before it is posted.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"The document to update"},"ledgerAccountId":{"description":"Ledger account id/number (Denmark)","type":"string"},"category":{"description":"Expense category (Italy / classification)","type":"string"},"vatCode":{"description":"VAT/IVA code","type":"string"},"bookingText":{"description":"The text/description of the booking","type":"string"},"codedAmount":{"description":"Signed amount to post (expenses are negative)","type":"number"}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/post_document":{"post":{"operationId":"post_document","summary":"Post document","description":"Post a coded document to the organization's accounting system as a journal entry and attach the source document. This writes to an external system, so it is reviewed before it runs unattended.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:post"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"The document to post"}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/retry_document":{"post":{"operationId":"retry_document","summary":"Retry document","description":"Clear the error on a failed document and re-run the appropriate step (extract, code or post).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"The document to retry"}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/set_region":{"post":{"operationId":"set_region","summary":"Set region","description":"Choose the organization's country/region. This selects the bookkeeping rules (VAT codes, account mapping) and the accounting provider used for posting.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["settings:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"regionKey":{"type":"string","enum":["denmark","italy"],"description":"The region to use: denmark or italy"},"defaultJournalId":{"description":"The journal / payment-account to post into","type":"string"}},"required":["regionKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/start_bank_authorization":{"post":{"operationId":"start_bank_authorization","summary":"Connect a bank","description":"Begin linking a bank account: returns a consent URL the user opens at their bank to authorize read-only access.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"institutionId":{"type":"string","description":"The bank/institution id from the institutions list"},"institutionName":{"description":"Display name of the bank","type":"string"}},"required":["institutionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/finalize_bank_authorization":{"post":{"operationId":"finalize_bank_authorization","summary":"Finish connecting a bank","description":"Complete a bank link after the user has authorized it: imports the authorized accounts.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"authorizationId":{"type":"string","description":"The bank authorization id returned by start_bank_authorization"}},"required":["authorizationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/sync_bank_now":{"post":{"operationId":"sync_bank_now","summary":"Sync bank transactions","description":"Pull the latest bank transactions for all connected accounts and auto-reconcile them.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/reconcile_now":{"post":{"operationId":"reconcile_now","summary":"Auto-reconcile","description":"Re-run automatic matching of unmatched bank transactions against posted ledger entries.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/match_transaction":{"post":{"operationId":"match_transaction","summary":"Match transaction","description":"Link a bank transaction to a posted ledger entry OR a captured document, marking it reconciled.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transactionId":{"type":"string","description":"The bank transaction to match"},"ledgerEntryId":{"description":"The ledger entry to match it to","type":"string"},"documentId":{"description":"The captured document to match it to (alternative to ledgerEntryId)","type":"string"}},"required":["transactionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/split_transaction":{"post":{"operationId":"split_transaction","summary":"Split-match transaction","description":"Reconcile a bank transaction across several targets (ledger entries and/or documents), each with an allocated amount.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transactionId":{"type":"string","description":"The bank transaction to match"},"allocations":{"minItems":1,"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","enum":["ledger","document"]},"targetId":{"type":"string"},"amount":{"type":"number","description":"Signed amount allocated to this target"}},"required":["targetType","targetId","amount"],"additionalProperties":false},"description":"The allocations that together cover the transaction"}},"required":["transactionId","allocations"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/unmatch_transaction":{"post":{"operationId":"unmatch_transaction","summary":"Unmatch transaction","description":"Remove the reconciliation link from a bank transaction, returning it to the review queue.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transactionId":{"type":"string","description":"The bank transaction to unmatch"}},"required":["transactionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/ignore_transaction":{"post":{"operationId":"ignore_transaction","summary":"Ignore transaction","description":"Mark a bank transaction as not needing reconciliation (e.g. internal transfer).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["bank:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transactionId":{"type":"string","description":"The bank transaction to ignore"}},"required":["transactionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/set_auto_post":{"post":{"operationId":"set_auto_post","summary":"Set auto-posting policy","description":"Enable or disable automatic posting of high-confidence coded documents (no human approval), and set the confidence threshold.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["settings:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"autoPost":{"type":"boolean","description":"Whether to auto-post high-confidence documents"},"autoPostThreshold":{"description":"Minimum extraction confidence to auto-post (0..1)","type":"number","minimum":0,"maximum":1}},"required":["autoPost"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/sync_chart_of_accounts":{"post":{"operationId":"sync_chart_of_accounts","summary":"Sync chart of accounts","description":"Refresh the cached chart of accounts from the accounting provider (Denmark / e-conomic).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["settings:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/generate_calendar_token":{"post":{"operationId":"generate_calendar_token","summary":"Generate calendar feed","description":"Create (or return) the token for the read-only iCalendar feed of accounting deadlines.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["settings:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/issue_einvoice":{"post":{"operationId":"issue_einvoice","summary":"Issue e-invoice","description":"Issue an outbound electronic invoice (Italy / SDI fattura elettronica) through the connected e-invoicing provider.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["invoices:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Buyer company or person name"},"vatNumber":{"description":"Partita IVA without country prefix","type":"string"},"fiscalCode":{"description":"Codice fiscale","type":"string"},"sdiCode":{"description":"Codice destinatario (7 chars; 0000000 for PEC)","type":"string"},"pec":{"description":"PEC delivery address","type":"string"},"country":{"description":"ISO 3166-1 alpha-2 country code of the buyer (drives VAT treatment)","type":"string"}},"required":["name"],"additionalProperties":false},"lines":{"minItems":1,"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unitPrice":{"type":"number","description":"Net unit price (VAT excluded)"},"vatRate":{"type":"number","description":"VAT rate percentage, e.g. 22"},"vatNature":{"description":"Natura IVA code (required when vatRate is 0)","type":"string"}},"required":["description","unitPrice","vatRate"],"additionalProperties":false}},"number":{"type":"string"},"date":{"description":"Invoice date YYYY-MM-DD","type":"string"},"currency":{"type":"string"},"causale":{"description":"Free-text causale","type":"string"}},"required":["buyer","lines"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/save_invoice":{"post":{"operationId":"save_invoice","summary":"Save invoice","description":"Create or update a draft outbound sales invoice addressed to a client contact. Totals and VAT treatment are derived from the buyer's country. Only drafts can be edited; an issued invoice is locked.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["invoices:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"Existing draft invoice id to update; omit to create","type":"string"},"contactId":{"type":"string","description":"The client contact this invoice is addressed to"},"number":{"description":"Invoice number (optional; a provider may assign one on issue)","type":"string"},"date":{"description":"Invoice date YYYY-MM-DD","type":"string"},"currency":{"description":"ISO 4217 currency; defaults to the org's currency","type":"string"},"lines":{"minItems":1,"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unitPrice":{"type":"number","description":"Net unit price (VAT excluded)"},"vatRate":{"type":"number","description":"VAT rate percentage, e.g. 22"}},"required":["description","unitPrice","vatRate"],"additionalProperties":false}}},"required":["contactId","lines"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_invoice":{"post":{"operationId":"delete_invoice","summary":"Delete invoice","description":"Delete a draft invoice. An issued invoice cannot be deleted.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["invoices:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"The draft invoice to delete"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/issue_invoice":{"post":{"operationId":"issue_invoice","summary":"Issue invoice","description":"Issue a stored draft invoice: transmit it through the region's e-invoicing provider (Italy / SDI) when available, otherwise record it as issued, and lock the record.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["invoices:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"The draft invoice to issue"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/set_vat_frequency":{"post":{"operationId":"set_vat_frequency","summary":"Set VAT filing frequency","description":"Set how often the organization files VAT (monthly, quarterly, half-yearly or annual). Affects deadlines and the return period.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["settings:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"frequency":{"anyOf":[{"type":"string","enum":["monthly","quarterly","half_yearly","annual"]},{"type":"null"}],"description":"The filing frequency, or null to use the region default"}},"required":["frequency"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/prepare_vat_return":{"post":{"operationId":"prepare_vat_return","summary":"Prepare VAT return","description":"Snapshot the current period's VAT/IVA return from posted ledger entries as a draft.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["ledger:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/file_vat_return":{"post":{"operationId":"file_vat_return","summary":"Mark VAT return filed","description":"Record a prepared VAT return as filed (optionally with the authority's reference).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["ledger:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"returnId":{"type":"string","description":"The prepared VAT return to mark filed"},"reference":{"description":"The filing reference from the tax authority","type":"string"}},"required":["returnId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/save_contact":{"post":{"operationId":"save_contact","summary":"Save contact","description":"Create or update a contact in the address book. A contact can be a client (you issue sales invoices to them), a vendor (you receive supplier documents from them), or both. The contact's country drives the VAT treatment of invoices and which fiscal id fields apply.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["invoices:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"Existing contact id to update; omit to create","type":"string"},"type":{"description":"client, vendor, or both (defaults to client)","type":"string","enum":["client","vendor","both"]},"name":{"type":"string","minLength":1},"businessId":{"description":"National registration id, e.g. Danish CVR (distinct from the EU VAT id)","type":"string"},"vatNumber":{"description":"EU VAT id (with country prefix for cross-border)","type":"string"},"fiscalCode":{"description":"Italian codice fiscale","type":"string"},"sdiCode":{"description":"Italian SDI destination code","type":"string"},"pec":{"description":"Italian PEC (certified email)","type":"string"},"country":{"description":"ISO 3166-1 alpha-2 country code","type":"string"},"email":{"type":"string"},"notes":{"type":"string"}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_contact":{"post":{"operationId":"delete_contact","summary":"Delete contact","description":"Remove a contact from the address book.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["invoices:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"The contact to delete"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/link_document_contact":{"post":{"operationId":"link_document_contact","summary":"Link document to contact","description":"Link a captured document to the vendor contact it came from (or pass a null contactId to unlink).","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:edit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"The document to link"},"contactId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The vendor contact to link to, or null to unlink"}},"required":["documentId","contactId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}},"/api/rest/actions/delete_document":{"post":{"operationId":"delete_document","summary":"Delete document","description":"Delete a captured document (receipt/invoice). Posted documents cannot be deleted.","tags":["actions"],"security":[{"ApiKeyAuth":[]}],"x-required-permissions":["documents:delete"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"The document to delete"}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Action result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key may not invoke this action"},"404":{"description":"Unknown action"}}}}}}