Fortnox (fortnox)

Category: io | Form: | Symbol: Fx

One Fortnox company - read vouchers, invoices, SIE, customers and financial years over OAuth2

Represents a single Fortnox company (Swedish cloud accounting, REST https://api.fortnox.se/3/) connected via OAuth2 authorization-code with rotating refresh tokens. Typed read-only op surface: company information, financial years, SIE export, vouchers, invoices, supplier invoices, customers, suppliers, cost centers, projects, accounts. Tokens are stored encrypted in the per-element OAuth2 credential store and auto-refreshed by the platform OAuth refresh worker. Resource ops route through the generalized declarative-REST executor; Bearer auth on /3/ calls, HTTP Basic only on the token-exchange/refresh arm. Read-only - no write-back to Fortnox.

Relationships

• Attaches to: rate-limit, auth-policy
• Uses: variable

Capabilities

• rest: Declarative-REST routed resource ops over the Fortnox /3/ API
• oauth2: OAuth2 authorization-code with rotating refresh tokens
• read-only: Read-only connector - no write-back to Fortnox

Properties

Property	Type	Default	Description
company_name	string	—	Display label for the connected Fortnox company
base_url	string	"https://api.fortnox.se"	Fortnox REST API base. Combined with each op’s declared rest.path by the declarative-REST executor.
authorize_url	string	"https://apps.fortnox.se/oauth-v1/auth"	Fortnox OAuth2 authorization endpoint
token_url	string	"https://apps.fortnox.se/oauth-v1/token"	Fortnox OAuth2 token endpoint
client_id	string	—	Fortnox integration Client ID from the Fortnox Developer Portal
client_secret_ref	string	—	Slug of the variable element holding the Fortnox Client Secret as a secret value. Never the secret itself. Used only on the HTTP Basic token-exchange/refresh arm.
redirect_uri	string	—	Optional OAuth2 redirect URI override. Omit to use the platform stable connector callback (/api/oauth/connect/callback), which routes to this element by signed state and can be shared by every circle/company using the same Fortnox app.
oauth	object	—	Optional generic OAuth2 connector config. Prefer profile_ref when the Fortnox client app is managed by Triform or a partner; top-level legacy fields remain supported for existing elements.
scopes	array	["companyinformation","bookkeeping","invoice","supplierinvoice","customer","supplier","costcenter","project","settings"]	OAuth2 scopes requested at consent
timeout_ms	integer	30000	Per-request timeout in milliseconds

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

download_archive_file

Post /ops/download_archive_file | Auth: Read

Download one archive document by file id. Binary: response data is base64 (encoding=base64) — decode to recover the PDF/image bytes.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_account

Post /ops/get_account | Auth: Read

Fetch one account by number, optionally for a financial year — carries Year/BalanceBroughtForward/BalanceCarriedForward (the FY-correct opening/closing balances).

get_company_information

Post /ops/get_company_information | Auth: Read

Fetch the connected company’s profile

get_company_settings

Post /ops/get_company_settings | Auth: Read

Full company settings: VATNumber, OrganizationNumber, CountryCode, TaxEnabled — drives VAT/reverse-charge logic. Heavier than get_company_information.

get_invoice

Post /ops/get_invoice | Auth: Read

Fetch one customer invoice by document number, including its rows.

get_locked_period

Post /ops/get_locked_period | Auth: Read

Return the locked-period EndDate — the last closed accounting date. Periods up to it are FINAL; later periods are provisional (figures may still move). Use to stamp reports final-vs-provisional.

get_sie

Post /ops/get_sie | Auth: Read

Download a SIE export (type 4 = full transactions). Pass financialYear explicitly — omitting it silently defaults to the CURRENT year. Sensitive: do not log SIE bodies.

get_supplier_invoice

Post /ops/get_supplier_invoice | Auth: Read

Fetch one supplier invoice by its given number, including its rows.

get_supplier_invoice_file_connections

Post /ops/get_supplier_invoice_file_connections | Auth: Read

List file connections between archive documents and supplier invoices

get_voucher

Post /ops/get_voucher | Auth: Read

Fetch one voucher’s full balanced TransactionRows by (series, number, financial year) — the drill-down when an anomaly review pins a journal entry.

get_voucher_file_connections

Post /ops/get_voucher_file_connections | Auth: Read

List file connections between archive documents and vouchers (which vouchers have a receipt)

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list_accounts

Post /ops/list_accounts | Auth: Read

List the chart of accounts (BAS). For per-year balances use get_account or get_sie — this list is not financial-year scoped.

list_archive

Post /ops/list_archive | Auth: Read

List archived documents (uploaded PDFs/images: receipts, invoices)

list_cost_centers

Post /ops/list_cost_centers | Auth: Read

List cost centers

list_customers

Post /ops/list_customers | Auth: Read

List customers

list_financial_years

Post /ops/list_financial_years | Auth: Read

List the company’s financial years

list_inbox

Post /ops/list_inbox | Auth: Read

List inbox items (documents uploaded but not yet booked/connected)

list_invoice_payments

Post /ops/list_invoice_payments | Auth: Read

List customer-invoice payments (AR settlement). Reconcile against list_invoices; do not also count the GL voucher for the same event.

list_invoices

Post /ops/list_invoices | Auth: Read

List customer invoices (AR). filter selects a lifecycle subset; pass fromdate/todate to bound the period.

list_predefined_accounts

Post /ops/list_predefined_accounts | Auth: Read

Map semantic roles (sales-VAT, AR, AP, rounding) to concrete account numbers for THIS company — the chart-agnostic way to find VAT/AR/AP accounts instead of hardcoding BAS ranges.

list_projects

Post /ops/list_projects | Auth: Read

List projects

list_supplier_invoice_payments

Post /ops/list_supplier_invoice_payments | Auth: Read

List supplier-invoice payments (AP settlement). Reconcile against list_supplier_invoices.

list_supplier_invoices

Post /ops/list_supplier_invoices | Auth: Read

List supplier invoices (AP). filter selects a lifecycle subset; pass fromdate/todate to bound the period.

list_suppliers

Post /ops/list_suppliers | Auth: Read

List suppliers

list_voucher_series

Post /ops/list_voucher_series | Auth: Read

List voucher series codes + descriptions (manual ‘A’, supplier ‘B’, etc.) — needed to label/slice the ledger and avoid double-counting system vs manual journals.

list_vouchers

Post /ops/list_vouchers | Auth: Read

List bookkeeping vouchers (GL journal entries). Pass financialyear — omitting it returns only the CURRENT financial year.

oauth_authorize

Post /ops/oauth_authorize | Auth: Write

Generate the Fortnox consent URL from OAuth config/profile scopes and a signed state

oauth_callback

Get /ops/oauth_callback | Auth: None

Exchange the authorization code for the first token pair and store it encrypted

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

receive

Post /ops/receive | Auth: None

Receive incoming external traffic

Entry point for external traffic reaching this IO element. Declared auth: none to bypass platform auth — element-level auth is enforced by IoReceiveExecutor before dispatching into the flow graph. The flow/app that wires this element as an entry point determines what happens next.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

send

Post /ops/send | Auth: Execute

Send a message/request to external system

Explicitly sends payload to the configured external target. For HTTP elements, POSTs to the target URL. For chat platforms, sends via the platform API. Put data in the payload field. Returns send status and response details.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

test_connection

Post /ops/test_connection | Auth: Read

Validate the stored token by calling a cheap authenticated endpoint

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
FORTNOX_NOT_CONNECTED	auth	no	No stored token pair - complete the OAuth2 consent first
FORTNOX_TOKEN_REFRESH_FAILED	auth	yes	Refresh attempt failed; the stored refresh token may be invalidated
FORTNOX_HTTP_ERROR	internal	yes	Fortnox returned a non-2xx response