StabisoDocs

API reference

Settings

The organization's reference-data sources and their status.

Operation Summary Scope Idempotency-Key
GET /v1/settings/controls Get the controls mode read
PUT /v1/settings/controls Set the controls mode admin
GET /v1/settings/data-sources Get the reference-data sources admin

GET /v1/settings/controls

Get the controls mode

The organization's controls mode: ai_reviewer (the default, where fixed checks decide each controlled step) or four_eyes (a second person decides, as before).
Required scope read (admin implies every scope)
Operation id get_controls_v1_settings_controls_get

Example request

curl "$ERP_URL/v1/settings/controls" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status Meaning Body
200 OK ControlsOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "controls": "string"
}

PUT /v1/settings/controls

Set the controls mode

An administrator sets the controls mode (ai_reviewer or four_eyes). The change applies at once and is recorded in the audit trail (controls.change). Switched to the AI reviewer, it decides at once the activations and postings that were waiting for a second person.
Required scope admin (admin implies every scope)
Idempotency-Key not used
Operation id put_controls_v1_settings_controls_put

Request body

application/json (required): ControlsIn

Field Type Required Description
controls string yes The controls mode: 'ai_reviewer' or 'four_eyes'.

Example request

curl -X PUT "$ERP_URL/v1/settings/controls" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "controls": "four_eyes"
}'

Responses

Status Meaning Body
200 OK ControlsOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
409 The request conflicts with the data: an Idempotency-Key reused with a different request, a closed period, or an integrity rule of the database (conflict, integrity_violation). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "controls": "string"
}

GET /v1/settings/data-sources

Get the reference-data sources

The reference data this organization needs and whether it arrives (admin).

The connection to data-vNext (in process or over HTTP, reachable, dataset version, latency, last error); the data points the organization's entities and features need, each with the reasons, the registered authority and its status (ok, stale, no_data, error, or gap when no authority is registered); and the other data points of the source register.
Required scope admin (admin implies every scope)
Operation id get_data_sources_v1_settings_data_sources_get

Example request

curl "$ERP_URL/v1/settings/data-sources" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status Meaning Body
200 OK DataSourcesOut
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "connection": {
    "mode": "http",
    "base_url": "string",
    "pinned_version": "string",
    "reachable": true,
    "dataset_version": "string",
    "latency_ms": 1.5,
    "checked_at": "2026-09-21T09:30:00Z",
    "last_error": "string",
    "last_error_at": "2026-09-21T09:30:00Z"
  },
  "as_of": "2026-09-21",
  "summary": {
    "needed": 1,
    "ok": 1,
    "stale": 1,
    "no_data": 1,
    "error": 1,
    "gap": 1,
    "unknown": 1,
    "available": 1
  },
  "needs": [
    {
      "domain": "string",
      "domain_title": "string",
      "jurisdictions": [
        "string"
      ],
      "reasons": [
        null
      ],
      "state": "error",
      "source": null
    }
  ],
  "other": [
    {
      "authority": "string",
      "authority_name": "string",
      "homepage": "string",
      "hosts": [
        "string"
      ],
      "licence": "string",
      "domain": "string",
      "domain_title": "string",
      "jurisdictions": [
        "string"
      ],
      "method": "string",
      "cadence": "string",
      "url": "string",
      "notes": "string",
      "used_by": [
        "string"
      ],
      "feeds": [
        null
      ],
      "records": [
        null
      ],
      "records_total": 0,
      "state": "error",
      "detail": "string",
      "latest_data": "2026-09-21",
      "last_run": null,
      "oldest_verified_at": "2026-09-21",
      "newest_verified_at": "2026-09-21",
      "cited_urls": 0,
      "watched_urls": 0,
      "unreachable_urls": [
        "string"
      ]
    }
  ],
  "customer_defined": [
    {
      "kind": "chart_of_accounts",
      "entity": "string",
      "entity_name": "string",
      "active": 1,
      "template": "string",
      "last_added_at": "2026-09-21T09:30:00Z"
    }
  ],
  "watcher": {
    "available": true,
    "run_date": "2026-09-21",
    "note": "string"
  },
  "status_error": "string"
}

Schemas

Connection

Field Type Required Description
mode "http" | "in_process" yes in_process (the reference data is loaded into the server) or http (a data-vNext service).
base_url string or null Address of the data-vNext service; null in process.
pinned_version string or null ERP_REFDATA_DATASET_VERSION, if every call is pinned.
reachable boolean yes True when the register answered.
dataset_version string or null Version of the reference dataset in use; null when unknown.
latency_ms number or null Round trip of the register.
checked_at string (date-time) yes When the connection was checked (ISO 8601, UTC).
last_error string or null The last connection error; null if none.
last_error_at string (date-time) or null When that error happened (ISO 8601, UTC); null if none.

ControlsIn

Field Type Required Description
controls string yes The controls mode: 'ai_reviewer' or 'four_eyes'.

ControlsOut

Field Type Required Description
controls string yes The controls mode: 'ai_reviewer' or 'four_eyes'.

CustomerDefined

Configuration the organization defines and maintains itself (not reference data).

Field Type Required Description
kind "chart_of_accounts" yes chart_of_accounts: the configuration is the entity's chart of accounts.
entity string yes Code of the entity.
entity_name string yes Name of the entity.
active integer yes Active accounts.
template string or null Chart template the entity started from, e.g. 'ch_kmu'.
last_added_at string (date-time) or null Newest account.

DataSource

One data point of the source register with its status.

Field Type Required Description
authority string yes Id of the authority in the source register.
authority_name string yes Name of the authority.
homepage string or null The authority's home page; null if none.
hosts array of string Host names the authority publishes the data on.
licence string or null Licence the data is published under; null if not stated.
domain string yes The kind of reference data, as in the register.
domain_title string yes Its name in words.
jurisdictions array of string yes The jurisdictions the data point covers.
method string yes How the register says the data is obtained.
cadence string or null How often the data changes; null if not stated.
url string or null Where the data is published; null if not stated.
notes string or null Remarks from the register; null if none.
used_by array of string Where the ERP uses this domain (the register).
feeds array of FeedOut The automatic feeds that keep the data current.
records array of RecordsOut How many records the data point holds, per dataset.
records_total integer Total number of records over all datasets. (default 0)
state "error" | "no_data" | "ok" | "stale" | "unknown" yes ok, stale (older than its freshness rule allows), no_data, error or unknown.
detail string or null A sentence explaining the state; null if none.
latest_data string (date) or null Newest stored date of the ingest feeds.
last_run IngestRunOut or null The most recent ingest run of its feeds.
oldest_verified_at string (date) or null The oldest date a maintainer last checked a record against its source (ISO 8601); null if none.
newest_verified_at string (date) or null The newest such check date (ISO 8601); null if none.
cited_urls integer Number of source URLs the records cite. (default 0)
watched_urls integer Number of those URLs that are watched for changes. (default 0)
unreachable_urls array of string Cited URLs that could not be reached at the last check.

DataSourcesOut

Field Type Required Description
connection Connection yes The connection to the reference-data service.
as_of string (date) or null The date the status refers to (ISO 8601).
summary Summary yes Counts of the needed data points by state.
needs array of Need yes The data points the organization's entities and features need.
other array of DataSource yes Registered data points the org does not need.
customer_defined array of CustomerDefined Defined by the organization: its charts of accounts.
watcher WatcherOut or null The legislation watcher's last run; null when there is none.
status_error string or null Why freshness is unknown (the register loaded, status not).

FeedOut

Field Type Required Description
id string yes Id of the feed.
kind "ingest" | "legislation" yes ingest (data fetched on a schedule) or legislation (watched for changes).
description string yes What the feed provides.
latest string (date) or null Newest date covered by the stored data (ISO 8601); null if none.
age_days integer or null How many days old the newest data is; null if none.
state "error" | "no_data" | "ok" | "stale" | "unknown" or null ok, stale (older than its freshness rule allows), no_data, error or unknown.
detail string or null A sentence explaining the state; null if none.
freshness string or null The freshness rule of the feed, in words; null if none.
max_age_days integer or null How old the newest data may be before it is stale; null if no limit.
min_horizon_days integer or null How far ahead the data must reach; null if no requirement.
last_run IngestRunOut or null The most recent ingest run of the feed; null if none.

IngestRunOut

Field Type Required Description
connector string yes Name of the connector that ran.
started_at string (date-time) yes When the run started (ISO 8601, UTC).
finished_at string (date-time) yes When it finished (ISO 8601, UTC).
ok boolean yes True when the run succeeded.
fetched integer Number of records fetched. (default 0)
stored integer Number of records stored. (default 0)
error string or null The error message when the run failed; null if it succeeded.
last_success_at string (date-time) or null When the connector last succeeded (ISO 8601, UTC); null if never.

Need

Field Type Required Description
domain string yes The kind of reference data, e.g. a tax rate or exchange rate dataset.
domain_title string yes Its name in words.
jurisdictions array of string yes Jurisdictions the entities need it for.
reasons array of NeedReason yes Which entities and features need it, and why.
state "error" | "gap" | "no_data" | "ok" | "stale" | "unknown" yes ok, stale, no_data, error, gap (no authority registered) or unknown.
source DataSource or null None: a gap (or unknown).

NeedReason

Field Type Required Description
entity string yes Code of the entity that needs the data.
entity_name string yes Name of that entity.
feature string yes One of FEATURES (vat_documents, vat_returns, ...).
text string yes Why it is needed, in a sentence.

RecordsOut

Field Type Required Description
dataset string yes Name of the dataset.
records integer yes Number of records in it.
series integer or null Number of series (e.g. currencies) in it; null if not a series dataset.

Summary

Field Type Required Description
needed integer yes Number of data points the organization needs.
ok integer yes Needed data points with state ok.
stale integer yes Needed data points with state stale.
no_data integer yes Needed data points with state no_data.
error integer yes Needed data points with state error.
gap integer yes Needed data points no registered authority covers.
unknown integer yes Needed data points whose state is not known.
available integer yes Data points in the register.

WatcherOut

Field Type Required Description
available boolean yes True when the legislation watcher has run.
run_date string (date) or null The date of its last run (ISO 8601); null if none.
note string or null A remark on the watcher; null if none.
Stabiso, the Enterprise System of Record · generated from the code and its guides · release 20b7dd5b0c4d