{ "openapi": "3.1.0", "info": { "title": "maticna.si API", "version": "1.0.0", "description": "REST API over the Slovenian FURS taxpayer lists (legal entities and sole proprietors). All responses carry `X-Request-Id`, `X-Data-As-Of` and `X-Data-Version`. Errors are RFC 9457 `application/problem+json`. Data source: FURS (Vir: FURS); financial statements: AJPES (Vir: AJPES, CC BY 4.0).", "contact": { "name": "maticna.si", "url": "https://maticna.si", "email": "api@maticna.si" } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer mk_…` (secret key; keys issued before 2026-10 start with `mk_live_` and keep working; browser keys: `mk_pub_…`)." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "ObjectionRequestInput": { "type": "object", "properties": { "tax_number": { "description": "Tax number of the s.p. (8 digits; `SI` prefix, spaces and dots accepted).", "example": "12345679", "type": "string", "maxLength": 32 }, "registration_number": { "description": "Registration number (matična številka), 7 or 10 digits.", "type": "string", "maxLength": 32 }, "name": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Name of the person objecting." }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Where the confirmation link is sent." }, "reason": { "description": "Free-text reason (optional).", "type": "string", "maxLength": 2000 }, "message": { "description": "Alias of `reason` (landing form).", "type": "string", "maxLength": 2000 }, "level": { "description": "`name_search` (default): leave name search, filters and SEO pages. `full`: also ask for removal from exact lookups (manual review).", "type": "string", "enum": [ "name_search", "full" ] }, "request_type": { "description": "Landing-form alias of `level`; `access` / `other` open a manual DSR.", "type": "string", "enum": [ "objection_name_search", "objection_full", "access", "other" ] }, "website": { "description": "Leave empty.", "type": "string", "maxLength": 500 } }, "required": [ "name", "email" ] }, "ObjectionRequest": { "type": "object", "properties": { "tax_number": { "description": "Tax number of the s.p. (8 digits; `SI` prefix, spaces and dots accepted).", "example": "12345679" }, "registration_number": { "description": "Registration number (matična številka), 7 or 10 digits." }, "name": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Name of the person objecting." }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Where the confirmation link is sent." }, "reason": { "description": "Free-text reason (optional)." }, "message": { "description": "Alias of `reason` (landing form)." }, "level": { "description": "`name_search` (default): leave name search, filters and SEO pages. `full`: also ask for removal from exact lookups (manual review).", "type": "string", "enum": [ "name_search", "full" ] }, "request_type": { "description": "Landing-form alias of `level`; `access` / `other` open a manual DSR.", "type": "string", "enum": [ "objection_name_search", "objection_full", "access", "other" ] }, "website": { "description": "Leave empty.", "type": "string", "maxLength": 500 } }, "required": [ "tax_number", "registration_number", "name", "email", "reason", "message" ], "additionalProperties": false }, "ObjectionAccepted": { "type": "object", "properties": { "object": { "type": "string", "const": "privacy_objection" }, "status": { "type": "string", "const": "pending_verification" }, "message": { "type": "string" } }, "required": [ "object", "status", "message" ], "additionalProperties": false }, "ObjectionConfirmed": { "type": "object", "properties": { "object": { "type": "string", "const": "privacy_objection" }, "status": { "type": "string", "enum": [ "applied", "in_review" ] }, "message": { "type": "string" } }, "required": [ "object", "status", "message" ], "additionalProperties": false }, "Entity": { "type": "object", "properties": { "object": { "type": "string", "const": "entity" }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "vat_id": { "type": "string", "pattern": "^SI\\d{8}$" }, "type": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "status_flags": { "type": "array", "items": { "type": "string", "enum": [ "in_bankruptcy", "in_liquidation" ] } }, "name": { "type": "string" }, "legal_form": { "type": [ "string", "null" ] }, "registration_number": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}$" }, { "type": "null" } ] }, "registration_number_short": { "anyOf": [ { "type": "string", "pattern": "^\\d{7}$" }, { "type": "null" } ] }, "foreign_registry_id": { "type": [ "string", "null" ] }, "address": { "type": "object", "properties": { "raw": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "raw", "street", "house_number", "postal_code", "city", "country" ], "additionalProperties": false }, "activity": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "label_sl": { "type": [ "string", "null" ] }, "label_en": { "type": [ "string", "null" ] }, "version": { "type": "string" } }, "required": [ "code", "label_sl", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "vat": { "type": "object", "properties": { "registered": { "type": "boolean" }, "registered_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "scope_code": { "anyOf": [ { "type": "string", "enum": [ "P", "O", "S", "Č" ] }, { "type": "null" } ] }, "group_id": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "furs_po", "furs_fo" ] }, { "type": "null" } ] } }, "required": [ "registered", "registered_on", "scope_code", "group_id", "source" ], "additionalProperties": false }, "vat_revocations": { "type": "array", "items": { "type": "object", "properties": { "list": { "type": "string", "enum": [ "mt", "np" ] }, "label": { "type": "string" }, "id_obtained_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "ceased_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "list", "label", "id_obtained_on", "ceased_on" ], "additionalProperties": false } }, "tax_office": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "registrations": { "type": "array", "items": { "type": "object", "properties": { "registration_number": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}$" }, { "type": "null" } ] }, "registration_number_short": { "anyOf": [ { "type": "string", "pattern": "^\\d{7}$" }, { "type": "null" } ] }, "foreign_registry_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "legal_form": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "status_flags": { "type": "array", "items": { "type": "string", "enum": [ "in_bankruptcy", "in_liquidation" ] } }, "address": { "type": "object", "properties": { "raw": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "raw", "street", "house_number", "postal_code", "city", "country" ], "additionalProperties": false }, "activity": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "label_sl": { "type": [ "string", "null" ] }, "label_en": { "type": [ "string", "null" ] }, "version": { "type": "string" } }, "required": [ "code", "label_sl", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "dataset": { "type": "string", "enum": [ "furs_po", "furs_dej", "furs_fo", "furs_mt", "furs_np", "furs_vat_groups" ] }, "first_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "last_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "deactivated_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "registration_number", "registration_number_short", "foreign_registry_id", "name", "type", "legal_form", "status", "status_flags", "address", "activity", "dataset", "first_seen_on", "last_seen_on", "deactivated_on" ], "additionalProperties": false } }, "first_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "last_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "deactivated_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "dataset": { "type": "string", "enum": [ "furs_po", "furs_dej", "furs_fo", "furs_mt", "furs_np", "furs_vat_groups" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "attribution": { "type": "string" }, "url": { "type": "string" } }, "required": [ "dataset", "as_of", "attribution", "url" ], "additionalProperties": false }, "match": { "type": "object", "properties": { "score": { "type": "number" }, "matched_on": { "type": "array", "items": { "type": "string" } } }, "required": [ "score", "matched_on" ], "additionalProperties": false } }, "required": [ "object", "tax_number", "vat_id", "type", "status", "status_flags", "name", "legal_form", "registration_number", "registration_number_short", "foreign_registry_id", "address", "activity", "vat", "vat_revocations", "tax_office", "registrations", "first_seen_on", "last_seen_on", "deactivated_on", "source" ], "additionalProperties": false }, "EntityList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor", "data_as_of" ], "additionalProperties": false }, "EntityWithIncludes": { "type": "object", "properties": { "object": { "type": "string", "const": "entity" }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "vat_id": { "type": "string", "pattern": "^SI\\d{8}$" }, "type": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "status_flags": { "type": "array", "items": { "type": "string", "enum": [ "in_bankruptcy", "in_liquidation" ] } }, "name": { "type": "string" }, "legal_form": { "type": [ "string", "null" ] }, "registration_number": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}$" }, { "type": "null" } ] }, "registration_number_short": { "anyOf": [ { "type": "string", "pattern": "^\\d{7}$" }, { "type": "null" } ] }, "foreign_registry_id": { "type": [ "string", "null" ] }, "address": { "type": "object", "properties": { "raw": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "raw", "street", "house_number", "postal_code", "city", "country" ], "additionalProperties": false }, "activity": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "label_sl": { "type": [ "string", "null" ] }, "label_en": { "type": [ "string", "null" ] }, "version": { "type": "string" } }, "required": [ "code", "label_sl", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "vat": { "type": "object", "properties": { "registered": { "type": "boolean" }, "registered_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "scope_code": { "anyOf": [ { "type": "string", "enum": [ "P", "O", "S", "Č" ] }, { "type": "null" } ] }, "group_id": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "furs_po", "furs_fo" ] }, { "type": "null" } ] } }, "required": [ "registered", "registered_on", "scope_code", "group_id", "source" ], "additionalProperties": false }, "vat_revocations": { "type": "array", "items": { "type": "object", "properties": { "list": { "type": "string", "enum": [ "mt", "np" ] }, "label": { "type": "string" }, "id_obtained_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "ceased_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "list", "label", "id_obtained_on", "ceased_on" ], "additionalProperties": false } }, "tax_office": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "registrations": { "type": "array", "items": { "type": "object", "properties": { "registration_number": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}$" }, { "type": "null" } ] }, "registration_number_short": { "anyOf": [ { "type": "string", "pattern": "^\\d{7}$" }, { "type": "null" } ] }, "foreign_registry_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "legal_form": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "status_flags": { "type": "array", "items": { "type": "string", "enum": [ "in_bankruptcy", "in_liquidation" ] } }, "address": { "type": "object", "properties": { "raw": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "raw", "street", "house_number", "postal_code", "city", "country" ], "additionalProperties": false }, "activity": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "label_sl": { "type": [ "string", "null" ] }, "label_en": { "type": [ "string", "null" ] }, "version": { "type": "string" } }, "required": [ "code", "label_sl", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "dataset": { "type": "string", "enum": [ "furs_po", "furs_dej", "furs_fo", "furs_mt", "furs_np", "furs_vat_groups" ] }, "first_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "last_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "deactivated_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "registration_number", "registration_number_short", "foreign_registry_id", "name", "type", "legal_form", "status", "status_flags", "address", "activity", "dataset", "first_seen_on", "last_seen_on", "deactivated_on" ], "additionalProperties": false } }, "first_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "last_seen_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "deactivated_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "dataset": { "type": "string", "enum": [ "furs_po", "furs_dej", "furs_fo", "furs_mt", "furs_np", "furs_vat_groups" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "attribution": { "type": "string" }, "url": { "type": "string" } }, "required": [ "dataset", "as_of", "attribution", "url" ], "additionalProperties": false }, "match": { "type": "object", "properties": { "score": { "type": "number" }, "matched_on": { "type": "array", "items": { "type": "string" } } }, "required": [ "score", "matched_on" ], "additionalProperties": false }, "financials_latest": { "description": "Only with `include=financials_latest`. `null`: no published financials (always for s.p.).", "anyOf": [ { "$ref": "#/components/schemas/FinancialsLatest" }, { "type": "null" } ] } }, "required": [ "object", "tax_number", "vat_id", "type", "status", "status_flags", "name", "legal_form", "registration_number", "registration_number_short", "foreign_registry_id", "address", "activity", "vat", "vat_revocations", "tax_office", "registrations", "first_seen_on", "last_seen_on", "deactivated_on", "source" ], "additionalProperties": false }, "EntityFinancials": { "type": "object", "properties": { "object": { "type": "string", "const": "financials" }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "registration_number": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}$" }, { "type": "null" } ] }, "coverage": { "$ref": "#/components/schemas/FinancialsCoverage" }, "currency": { "type": "string", "const": "EUR" }, "source": { "$ref": "#/components/schemas/FinancialsSource" }, "access": { "$ref": "#/components/schemas/FinancialsAccess" }, "years": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialYear" }, "description": "Newest first." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "example": 2023 }, "report_type": { "type": "string", "description": "AJPES report type (vrstalp), e.g. `06` audited, `07` consolidated, `72` eRLP, `73` eKLP.", "example": "06" }, "doc_name": { "description": "AJPES document name (RLP, KLP, eRLP, eKLP …).", "example": "RLP", "type": [ "string", "null" ] }, "label": { "example": "Revidirano letno poročilo", "type": [ "string", "null" ] }, "label_en": { "example": "Audited annual report", "type": [ "string", "null" ] }, "format": { "description": "File format: `pdf`, `zip` (ESEF report package) …", "example": "pdf", "type": [ "string", "null" ] }, "size_bytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "published_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "period_end": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "structured": { "type": "boolean", "description": "`true`: maticna.si read the figures in `years` from this document (ESEF)." }, "url": { "type": "string", "description": "AJPES's public page of the company's published annual reports (JOLP). AJPES asks you to sign in there (free registration, or as an anonymous user) and allows 20 companies a day.", "example": "https://www.ajpes.si/jolp/podjetje.asp?maticna=5025796000" } }, "required": [ "year", "report_type", "doc_name", "label", "label_en", "format", "size_bytes", "published_on", "period_end", "structured", "url" ], "additionalProperties": false }, "description": "Documents AJPES lists for the same business years (newest first): audited and consolidated reports as PDF or ESEF ZIP. Years without figures in `years` often have one here." }, "as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ], "description": "Newest source date among the years served." } }, "required": [ "object", "tax_number", "registration_number", "coverage", "currency", "source", "access", "years", "documents", "as_of" ], "additionalProperties": false }, "FinancialYear": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Business year (poslovno leto).", "example": 2025 }, "report_type": { "type": "string", "example": "01" }, "basis": { "type": "string", "enum": [ "standalone", "consolidated" ], "description": "Basis of `figures`: `standalone` whenever the company's own statements exist, else `consolidated`." }, "source_format": { "type": "string", "enum": [ "ajpes_json", "esef" ], "description": "`ajpes_json`: AJPES's structured table (rows T001…); `esef`: read by maticna.si from the ESEF (iXBRL, IFRS) annual report AJPES publishes." }, "period_start": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "period_end": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "period_months": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Shorter than 12 for a first, last or changed business year." }, "size_class": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "AJPES size class 1–4 (micro … large) when the source gives it." }, "currency": { "type": "string", "const": "EUR" }, "quality": { "type": "string", "enum": [ "ok", "warning" ], "description": "`warning`: the balance-sheet net result differs from the income statement (served; reports that fail the balance checks are never served)." }, "restated": { "type": "boolean", "description": "AJPES corrected the report after first publication." }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "figures": { "type": "object", "properties": { "total_assets": { "type": [ "number", "null" ] }, "non_current_assets": { "type": [ "number", "null" ] }, "current_assets": { "type": [ "number", "null" ] }, "inventories": { "type": [ "number", "null" ] }, "receivables": { "type": [ "number", "null" ] }, "cash": { "type": [ "number", "null" ] }, "equity": { "type": [ "number", "null" ] }, "share_capital": { "type": [ "number", "null" ] }, "provisions": { "type": [ "number", "null" ] }, "long_term_liabilities": { "type": [ "number", "null" ] }, "short_term_liabilities": { "type": [ "number", "null" ] }, "financial_debt": { "type": [ "number", "null" ] }, "liabilities": { "type": [ "number", "null" ] }, "revenue": { "type": [ "number", "null" ] }, "operating_revenue": { "type": [ "number", "null" ] }, "operating_expenses": { "type": [ "number", "null" ] }, "ebit": { "type": [ "number", "null" ] }, "ebitda": { "type": [ "number", "null" ] }, "depreciation": { "type": [ "number", "null" ] }, "financial_income": { "type": [ "number", "null" ] }, "financial_expenses": { "type": [ "number", "null" ] }, "income_tax": { "type": [ "number", "null" ] }, "net_profit": { "type": [ "number", "null" ] }, "employees": { "type": [ "number", "null" ] } }, "additionalProperties": false, "description": "Key figures in EUR (`employees`: average number, from hours worked). `null`: not reported. Only the figures of your plan are present." }, "methods": { "type": "object", "properties": { "total_assets": { "type": "string", "enum": [ "official", "derived" ] }, "non_current_assets": { "type": "string", "enum": [ "official", "derived" ] }, "current_assets": { "type": "string", "enum": [ "official", "derived" ] }, "inventories": { "type": "string", "enum": [ "official", "derived" ] }, "receivables": { "type": "string", "enum": [ "official", "derived" ] }, "cash": { "type": "string", "enum": [ "official", "derived" ] }, "equity": { "type": "string", "enum": [ "official", "derived" ] }, "share_capital": { "type": "string", "enum": [ "official", "derived" ] }, "provisions": { "type": "string", "enum": [ "official", "derived" ] }, "long_term_liabilities": { "type": "string", "enum": [ "official", "derived" ] }, "short_term_liabilities": { "type": "string", "enum": [ "official", "derived" ] }, "financial_debt": { "type": "string", "enum": [ "official", "derived" ] }, "liabilities": { "type": "string", "enum": [ "official", "derived" ] }, "revenue": { "type": "string", "enum": [ "official", "derived" ] }, "operating_revenue": { "type": "string", "enum": [ "official", "derived" ] }, "operating_expenses": { "type": "string", "enum": [ "official", "derived" ] }, "ebit": { "type": "string", "enum": [ "official", "derived" ] }, "ebitda": { "type": "string", "enum": [ "official", "derived" ] }, "depreciation": { "type": "string", "enum": [ "official", "derived" ] }, "financial_income": { "type": "string", "enum": [ "official", "derived" ] }, "financial_expenses": { "type": "string", "enum": [ "official", "derived" ] }, "income_tax": { "type": "string", "enum": [ "official", "derived" ] }, "net_profit": { "type": "string", "enum": [ "official", "derived" ] }, "employees": { "type": "string", "enum": [ "official", "derived" ] } }, "additionalProperties": false, "description": "`official`: one published AJPES row or one tagged IFRS concept; `derived`: computed by maticna.si (formula in the docs)." }, "provenance": { "type": "object", "properties": { "bilanca_stanja": { "$ref": "#/components/schemas/FinancialsProvenance" }, "izkaz_poslovnega_izida": { "$ref": "#/components/schemas/FinancialsProvenance" } }, "required": [ "bilanca_stanja", "izkaz_poslovnega_izida" ], "additionalProperties": false }, "items": { "description": "Raw line items. AJPES table: `T001`… current year, `P001`… previous year (the number is the row of the AJPES public table). ESEF: `T:` / `P:` + the XBRL concept (`T:ifrs-full:Revenue`, company extensions too), EUR. Only with `include=items` (Growth plan and up).", "type": "object", "propertyNames": { "type": "string", "pattern": "^([TP]\\d{3}|[TP]:[A-Za-z_][\\w.-]*:[A-Za-z_][\\w.-]*)$" }, "additionalProperties": { "type": "number" } }, "consolidated": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "standalone", "consolidated" ], "description": "`standalone`: the company alone (posamični izkazi); `consolidated`: the group (konsolidirani izkazi; ESEF reports only)." }, "report_type": { "type": "string" }, "source_format": { "type": "string", "enum": [ "ajpes_json", "esef" ], "description": "`ajpes_json`: AJPES's structured table (rows T001…); `esef`: read by maticna.si from the ESEF (iXBRL, IFRS) annual report AJPES publishes." }, "quality": { "type": "string", "enum": [ "ok", "warning" ] }, "restated": { "type": "boolean" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "figures": { "type": "object", "properties": { "total_assets": { "type": [ "number", "null" ] }, "non_current_assets": { "type": [ "number", "null" ] }, "current_assets": { "type": [ "number", "null" ] }, "inventories": { "type": [ "number", "null" ] }, "receivables": { "type": [ "number", "null" ] }, "cash": { "type": [ "number", "null" ] }, "equity": { "type": [ "number", "null" ] }, "share_capital": { "type": [ "number", "null" ] }, "provisions": { "type": [ "number", "null" ] }, "long_term_liabilities": { "type": [ "number", "null" ] }, "short_term_liabilities": { "type": [ "number", "null" ] }, "financial_debt": { "type": [ "number", "null" ] }, "liabilities": { "type": [ "number", "null" ] }, "revenue": { "type": [ "number", "null" ] }, "operating_revenue": { "type": [ "number", "null" ] }, "operating_expenses": { "type": [ "number", "null" ] }, "ebit": { "type": [ "number", "null" ] }, "ebitda": { "type": [ "number", "null" ] }, "depreciation": { "type": [ "number", "null" ] }, "financial_income": { "type": [ "number", "null" ] }, "financial_expenses": { "type": [ "number", "null" ] }, "income_tax": { "type": [ "number", "null" ] }, "net_profit": { "type": [ "number", "null" ] }, "employees": { "type": [ "number", "null" ] } }, "additionalProperties": false, "description": "Key figures in EUR (`employees`: average number, from hours worked). `null`: not reported. Only the figures of your plan are present." }, "methods": { "type": "object", "properties": { "total_assets": { "type": "string", "enum": [ "official", "derived" ] }, "non_current_assets": { "type": "string", "enum": [ "official", "derived" ] }, "current_assets": { "type": "string", "enum": [ "official", "derived" ] }, "inventories": { "type": "string", "enum": [ "official", "derived" ] }, "receivables": { "type": "string", "enum": [ "official", "derived" ] }, "cash": { "type": "string", "enum": [ "official", "derived" ] }, "equity": { "type": "string", "enum": [ "official", "derived" ] }, "share_capital": { "type": "string", "enum": [ "official", "derived" ] }, "provisions": { "type": "string", "enum": [ "official", "derived" ] }, "long_term_liabilities": { "type": "string", "enum": [ "official", "derived" ] }, "short_term_liabilities": { "type": "string", "enum": [ "official", "derived" ] }, "financial_debt": { "type": "string", "enum": [ "official", "derived" ] }, "liabilities": { "type": "string", "enum": [ "official", "derived" ] }, "revenue": { "type": "string", "enum": [ "official", "derived" ] }, "operating_revenue": { "type": "string", "enum": [ "official", "derived" ] }, "operating_expenses": { "type": "string", "enum": [ "official", "derived" ] }, "ebit": { "type": "string", "enum": [ "official", "derived" ] }, "ebitda": { "type": "string", "enum": [ "official", "derived" ] }, "depreciation": { "type": "string", "enum": [ "official", "derived" ] }, "financial_income": { "type": "string", "enum": [ "official", "derived" ] }, "financial_expenses": { "type": "string", "enum": [ "official", "derived" ] }, "income_tax": { "type": "string", "enum": [ "official", "derived" ] }, "net_profit": { "type": "string", "enum": [ "official", "derived" ] }, "employees": { "type": "string", "enum": [ "official", "derived" ] } }, "additionalProperties": false, "description": "`official`: one published AJPES row or one tagged IFRS concept; `derived`: computed by maticna.si (formula in the docs)." }, "provenance": { "type": "object", "properties": { "bilanca_stanja": { "$ref": "#/components/schemas/FinancialsProvenance" }, "izkaz_poslovnega_izida": { "$ref": "#/components/schemas/FinancialsProvenance" } }, "required": [ "bilanca_stanja", "izkaz_poslovnega_izida" ], "additionalProperties": false }, "items": { "description": "Raw line items. AJPES table: `T001`… current year, `P001`… previous year (the number is the row of the AJPES public table). ESEF: `T:` / `P:` + the XBRL concept (`T:ifrs-full:Revenue`, company extensions too), EUR. Only with `include=items` (Growth plan and up).", "type": "object", "propertyNames": { "type": "string", "pattern": "^([TP]\\d{3}|[TP]:[A-Za-z_][\\w.-]*:[A-Za-z_][\\w.-]*)$" }, "additionalProperties": { "type": "number" } } }, "required": [ "basis", "report_type", "source_format", "quality", "restated", "revision", "figures", "methods", "provenance" ], "additionalProperties": false }, { "type": "null" } ], "description": "The group's (consolidated) figures of the same year when the ESEF report has them and `figures` are standalone; `null` otherwise. Same plan rules as `figures`." } }, "required": [ "year", "report_type", "basis", "source_format", "period_start", "period_end", "period_months", "size_class", "currency", "quality", "restated", "revision", "figures", "methods", "provenance", "consolidated" ], "additionalProperties": false }, "FinancialsLatest": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "period_start": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "period_end": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "period_months": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "type": "string", "const": "EUR" }, "figures": { "type": "object", "properties": { "revenue": { "type": [ "number", "null" ] }, "net_profit": { "type": [ "number", "null" ] }, "employees": { "type": [ "number", "null" ] }, "total_assets": { "type": [ "number", "null" ] }, "equity": { "type": [ "number", "null" ] } }, "required": [ "revenue", "net_profit", "employees", "total_assets", "equity" ], "additionalProperties": false }, "provenance": { "type": "object", "properties": { "bilanca_stanja": { "$ref": "#/components/schemas/FinancialsProvenance" }, "izkaz_poslovnega_izida": { "$ref": "#/components/schemas/FinancialsProvenance" } }, "required": [ "bilanca_stanja", "izkaz_poslovnega_izida" ], "additionalProperties": false }, "attribution": { "type": "string" } }, "required": [ "year", "period_start", "period_end", "period_months", "currency", "figures", "provenance", "attribution" ], "additionalProperties": false }, "FinancialsProvenance": { "type": "object", "properties": { "dataset": { "type": "string", "const": "ajpes_lp" }, "source": { "type": "string", "example": "AJPES – letna poročila" }, "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "statement": { "type": "string", "enum": [ "bilanca_stanja", "izkaz_poslovnega_izida" ] }, "report_type": { "type": "string", "description": "AJPES report type (vrstalp); `01` = annual report (structured table), `72` = audited annual report (eRLP), `73` = consolidated annual report (eKLP).", "example": "01" }, "basis": { "type": "string", "enum": [ "standalone", "consolidated" ], "description": "`standalone`: the company alone (posamični izkazi); `consolidated`: the group (konsolidirani izkazi; ESEF reports only)." }, "period_end": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "published_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "updated_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ], "description": "AJPES correction date, when the report was corrected." }, "as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ], "description": "The source date: `updated_on`, else `published_on`." }, "fetched_at": { "type": "string", "description": "When maticna.si fetched the report (ISO 8601)." }, "licence": { "type": "string", "example": "CC-BY-4.0" }, "licence_url": { "type": [ "string", "null" ] }, "attribution": { "type": "string", "description": "Show it next to the figures and pass it on (CC BY 4.0).", "example": "Vir: AJPES (www.ajpes.si), CC BY 4.0; izračuni maticna.si" }, "url": { "type": "string" }, "method": { "type": "string", "enum": [ "official", "derived" ] } }, "required": [ "dataset", "source", "year", "statement", "report_type", "basis", "period_end", "published_on", "updated_on", "as_of", "fetched_at", "licence", "licence_url", "attribution", "url", "method" ], "additionalProperties": false }, "FinancialsSource": { "type": "object", "properties": { "dataset": { "type": "string", "const": "ajpes_lp" }, "name": { "type": "string", "example": "AJPES – letna poročila" }, "name_en": { "type": "string" }, "publisher": { "type": "string" }, "url": { "type": "string" }, "licence": { "type": "string" }, "licence_url": { "type": [ "string", "null" ] }, "attribution": { "type": "string" }, "attribution_required": { "type": "boolean", "const": true } }, "required": [ "dataset", "name", "name_en", "publisher", "url", "licence", "licence_url", "attribution", "attribution_required" ], "additionalProperties": false }, "FinancialsCoverage": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "documents_only", "no_reports", "not_covered" ], "description": "`available`: at least one year of figures; `documents_only`: AJPES publishes this company's reports only as documents (e.g. an audited report in PDF), see `documents`; `no_reports`: a company AJPES covers, no published report yet; `not_covered`: no financials for this taxpayer (see `reason`)." }, "reason": { "anyOf": [ { "type": "string", "enum": [ "natural_person", "legal_form_not_covered" ] }, { "type": "null" } ], "description": "`natural_person`: sole proprietors (s.p.) and other natural persons; never served. `legal_form_not_covered`: AJPES publishes no structured reports for this legal form." }, "detail": { "type": "string" }, "detail_sl": { "type": "string", "description": "The same in Slovenian." } }, "required": [ "status", "reason", "detail", "detail_sl" ], "additionalProperties": false }, "FinancialsAccess": { "type": "object", "properties": { "plan": { "type": "string" }, "max_years": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "figures": { "type": "string", "enum": [ "summary", "full" ] }, "items": { "type": "boolean" }, "years_capped": { "type": "boolean", "description": "`true` when you asked for more years than your plan serves." } }, "required": [ "plan", "max_years", "figures", "items", "years_capped" ], "additionalProperties": false }, "AutocompleteItem": { "type": "object", "properties": { "object": { "type": "string", "const": "autocomplete_item" }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "legal_form": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "vat_registered": { "type": "boolean" } }, "required": [ "object", "tax_number", "name", "type", "legal_form", "city", "postal_code", "vat_registered" ], "additionalProperties": false }, "BulkLookupResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "bulk_lookup" }, "data": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "id_kind": { "anyOf": [ { "type": "string", "enum": [ "tax_number", "vat_id", "registration_number", "registration_number_short" ] }, { "type": "null" } ] }, "found": { "type": "boolean" }, "entity": { "anyOf": [ { "$ref": "#/components/schemas/Entity" }, { "type": "null" } ] }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "key_in_query_forbidden", "missing_api_key", "invalid_api_key", "key_revoked", "key_expired", "test_keys_removed", "payment_required", "insufficient_scope", "plan_upgrade_required", "origin_not_allowed", "monitor_limit_reached", "webhook_endpoint_limit_reached", "ip_not_allowed", "not_found", "not_vat_registered", "cursor_expired", "idempotency_conflict", "invalid_tax_number", "invalid_vat_id", "invalid_registration_number", "query_too_short", "invalid_webhook_url", "rate_limited", "quota_exceeded", "natural_person_cap_exceeded", "internal_error", "upstream_stale", "search_timeout" ] }, "detail": { "type": "string" } }, "required": [ "code" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "input", "id_kind", "found", "entity", "error" ], "additionalProperties": false } }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "object", "data", "data_as_of" ], "additionalProperties": false }, "VatCheck": { "type": "object", "properties": { "object": { "type": "string", "const": "vat_check" }, "vat_id": { "type": "string" }, "valid_format": { "type": "boolean" }, "registered": { "type": "boolean" }, "registered_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "scope_code": { "anyOf": [ { "type": "string", "enum": [ "P", "O", "S", "Č" ] }, { "type": "null" } ] }, "group_id": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$" }, { "type": "null" } ] }, "revocations": { "type": "array", "items": { "type": "object", "properties": { "list": { "type": "string", "enum": [ "mt", "np" ] }, "label": { "type": "string" }, "id_obtained_on": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "ceased_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "list", "label", "id_obtained_on", "ceased_on" ], "additionalProperties": false } }, "entity_ref": { "anyOf": [ { "type": "object", "properties": { "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "tax_number", "name", "type" ], "additionalProperties": false }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "object", "vat_id", "valid_format", "registered", "registered_on", "scope_code", "group_id", "revocations", "entity_ref", "data_as_of" ], "additionalProperties": false }, "TaxNumberCheck": { "type": "object", "properties": { "object": { "type": "string", "const": "tax_number_check" }, "tax_number": { "type": "string" }, "valid_checksum": { "type": "boolean" }, "exists": { "type": "boolean" }, "entity_ref": { "anyOf": [ { "type": "object", "properties": { "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "tax_number", "name", "type" ], "additionalProperties": false }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "object", "tax_number", "valid_checksum", "exists", "entity_ref", "data_as_of" ], "additionalProperties": false }, "MetaStatus": { "type": "object", "properties": { "object": { "type": "string", "const": "status" }, "status": { "type": "string", "enum": [ "ok", "degraded", "stale" ] }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "data_version": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "datasets": { "type": "array", "items": { "type": "object", "properties": { "dataset": { "type": "string", "enum": [ "furs_po", "furs_dej", "furs_fo", "furs_mt", "furs_np", "furs_vat_groups" ] }, "source_date": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "last_run_at": { "type": [ "string", "null" ] }, "last_run_status": { "type": [ "string", "null" ] }, "guard_result": { "type": [ "string", "null" ] }, "row_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "data_version": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "stale": { "type": "boolean" } }, "required": [ "dataset", "source_date", "last_run_at", "last_run_status", "guard_result", "row_count", "data_version", "stale" ], "additionalProperties": false } }, "attribution": { "type": "string" } }, "required": [ "object", "status", "data_as_of", "data_version", "datasets", "attribution" ], "additionalProperties": false }, "ReferenceList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "kind": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label_sl": { "type": "string" }, "label_en": { "type": [ "string", "null" ] }, "level": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "parent_code": { "type": [ "string", "null" ] } }, "required": [ "code", "label_sl", "label_en" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "const": false }, "next_cursor": { "type": "null" }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "object", "kind", "data", "has_more", "next_cursor", "data_as_of" ], "additionalProperties": false }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "const": "usage" }, "plan": { "type": "string" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "units_used": { "type": "number" }, "units_included": { "type": "number" }, "credits_remaining": { "type": "number" }, "units_remaining": { "type": "number" }, "hard_cap": { "type": "boolean" }, "daily_cap": { "type": [ "number", "null" ] }, "daily_used": { "type": [ "number", "null" ] }, "key": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "channel": { "type": "string", "enum": [ "key", "playground" ] }, "units_used": { "type": "number" }, "monthly_cap": { "type": [ "number", "null" ] } }, "required": [ "id", "channel", "units_used", "monthly_cap" ], "additionalProperties": false } }, "required": [ "object", "plan", "period_start", "period_end", "units_used", "units_included", "credits_remaining", "units_remaining", "hard_cap", "daily_cap", "daily_used", "key" ], "additionalProperties": false }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "bad_request", "key_in_query_forbidden", "missing_api_key", "invalid_api_key", "key_revoked", "key_expired", "test_keys_removed", "payment_required", "insufficient_scope", "plan_upgrade_required", "origin_not_allowed", "monitor_limit_reached", "webhook_endpoint_limit_reached", "ip_not_allowed", "not_found", "not_vat_registered", "cursor_expired", "idempotency_conflict", "invalid_tax_number", "invalid_vat_id", "invalid_registration_number", "query_too_short", "invalid_webhook_url", "rate_limited", "quota_exceeded", "natural_person_cap_exceeded", "internal_error", "upstream_stale", "search_timeout" ] }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" } }, "required": [ "field", "code" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": false }, "ChangeList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "change" }, "id": { "type": "string" }, "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "change_type": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "registration_number": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ] }, "changed_fields": { "type": "array", "items": { "type": "string" } }, "before": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Snapshot of the compared fields (entity changes: type, status, name, legal_form, status_flags, registration_number, address_raw, street, house_number, postcode, city, country, activity_code, tax_office_code; VAT changes: registered, registered_on; revocations: list, id_obtained_on, ceased_on). null when redacted." }, { "type": "null" } ] }, "after": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Snapshot of the compared fields (entity changes: type, status, name, legal_form, status_flags, registration_number, address_raw, street, house_number, postcode, city, country, activity_code, tax_office_code; VAT changes: registered, registered_on; revocations: list, id_obtained_on, ceased_on). null when redacted." }, { "type": "null" } ] }, "source_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "detected_at": { "type": "string" }, "data_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "redacted": { "type": "boolean" } }, "required": [ "object", "id", "seq", "change_type", "tax_number", "registration_number", "type", "name", "changed_fields", "before", "after", "source_date", "detected_at", "data_version", "redacted" ], "additionalProperties": false, "description": "One change detected in the FURS lists." } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor", "data_as_of" ], "additionalProperties": false }, "MonitorList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "monitor" }, "id": { "type": "string" }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "label": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "object", "id", "tax_number", "label", "created_at" ], "additionalProperties": false, "description": "A watched tax number. Changes of every registration under it are delivered to the org’s webhook endpoints." } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "slots": { "type": "object", "properties": { "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "used", "limit" ], "additionalProperties": false } }, "required": [ "object", "data", "has_more", "next_cursor", "slots" ], "additionalProperties": false }, "WebhookEndpointWithSecret": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_endpoint" }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] }, "description": "Change types delivered; empty = all." }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "user", "consecutive_failures", "plan_downgraded" ] }, { "type": "null" } ], "description": "`user`: disabled by you. `consecutive_failures`: 20 failed attempts in a row. `plan_downgraded`: the plan no longer includes webhooks; the endpoint is re-enabled automatically after an upgrade (events from the downgraded period are not replayed)." }, "secret_hint": { "type": "string", "description": "Last 4 characters of the signing secret.", "example": "whsec_…k3Xa" }, "previous_secret_expires_at": { "description": "After a secret roll: until when events are also signed with the previous secret (a second `v1,` signature). null when there is none.", "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "secret": { "type": "string", "description": "The `whsec_…` signing secret. Returned only once: on creation and on a secret roll." } }, "required": [ "object", "id", "url", "description", "event_types", "enabled", "disabled_reason", "secret_hint", "previous_secret_expires_at", "created_at", "updated_at", "secret" ], "additionalProperties": false } } }, "paths": { "/v1/entities/{tax_number}": { "get": { "operationId": "getEntity", "summary": "Get a taxpayer by tax number", "tags": [ "Entities" ], "description": "Accepts `SI12345678`. A well-formed but unknown number returns 404 `not_found` (billable: \"does not exist\" is the product). `include=financials_latest` adds the newest AJPES annual-report summary (revenue, net profit, employees, assets, equity) with provenance, Starter and up (Hobi: 403 `plan_upgrade_required`, 0 units): +1 unit when a summary is returned, `null` (no extra unit) for s.p. and companies without a report.", "parameters": [ { "schema": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "enum": [ "financials_latest" ] } }, "in": "query", "name": "include", "required": false, "description": "`financials_latest`: the newest AJPES annual-report summary (+1 unit when one is returned)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "19000006" }, "in": "path", "name": "tax_number", "required": true, "description": "Slovenian tax number (8 digits); an `SI` prefix, spaces and dots are accepted." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityWithIncludes" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/entities/by-registration-number/{registration_number}": { "get": { "operationId": "getEntitiesByRegistrationNumber", "summary": "Find entities by registration number (matična številka)", "tags": [ "Entities" ], "description": "10 digits returns that unit; 7 digits returns all units and branches sharing the short number.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "9000000010" }, "in": "path", "name": "registration_number", "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityList" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/entities/by-vat/{vat_id}": { "get": { "operationId": "getEntityByVatId", "summary": "Get a taxpayer by Slovenian VAT ID", "tags": [ "Entities" ], "description": "Returns 404 `not_vat_registered` (with a `Link` to the taxpayer) when the entity exists but is not VAT registered.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "SI19000006" }, "in": "path", "name": "vat_id", "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/entities/lookup": { "post": { "operationId": "bulkLookup", "summary": "Look up to 100 mixed identifiers", "tags": [ "Entities" ], "description": "Tax numbers, VAT IDs and registration numbers (7 or 10 digits) in any mix. Results come back in input order. Starter plan and up (plan feature `bulk_lookup`; Hobi gets 403 `plan_upgrade_required`, 0 units). Billed 1 unit per distinct well-formed ID, found or not. Send `Idempotency-Key` to make retries free for 24 h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "required": [ "ids" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "idempotency-key", "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupResponse" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Cursor expired or idempotency conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/entities": { "get": { "operationId": "searchEntities", "summary": "Search and filter taxpayers", "tags": [ "Search" ], "description": "Relevance search when `q` is set (name, or an exact tax/registration number), otherwise a filtered listing ordered by tax number. `limit` default 20, max 50. Pagination is cursor-based and capped at 1,000 results (50 when filtering to natural persons). A cursor issued before a data refresh returns 409 `cursor_expired`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}$" }, "in": "query", "name": "postal_code", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "city", "required": false }, { "schema": { "type": "string", "pattern": "^[A-Z]?\\d{0,2}(\\.\\d{1,3})?$|^[A-U]$" }, "in": "query", "name": "activity_code", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "vat_registered", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 30 }, "in": "query", "name": "legal_form", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{2}$" }, "in": "query", "name": "tax_office", "required": false }, { "schema": { "type": "string", "enum": [ "relevance", "name", "tax_number" ] }, "in": "query", "name": "sort", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityList" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Cursor expired or idempotency conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/entities/{tax_number}/financials": { "get": { "operationId": "getEntityFinancials", "summary": "Annual-report financial statements of a company", "tags": [ "Financials" ], "description": "Key figures from the AJPES annual reports (balance sheet and income statement), newest year first, each statement with a provenance stamp (source, year, publication / correction date, licence, attribution). Figures come from AJPES's structured table or, for large audited companies, from their ESEF (iXBRL) annual report: `figures` are the company's own (standalone) statements and `consolidated` the group's of the same year. `documents` lists the reports AJPES publishes only as files (e.g. audited reports in PDF) with a link to AJPES; a company with documents only has `coverage.status = documents_only`. Capital companies (d.o.o., d.d., k.d.d., SE) and cooperatives only: sole proprietors (s.p.) return `coverage.status = not_covered` with `reason = natural_person` and no figures, never data. Hobi: not included (403 `plan_upgrade_required`, 0 units); Starter: last 3 years, summary; Growth and Custom: up to 10 years, all figures and `include=items` (raw AJPES line items; below Growth 403 `plan_upgrade_required`). A well-formed unknown tax number returns 404 (billable, like a lookup). 1 unit. Licence CC BY 4.0: keep the `source.attribution` text with the figures you show or pass on.", "parameters": [ { "schema": { "default": 5, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "years", "required": false, "description": "Newest N business years (default 5, max 10); capped by the plan." }, { "schema": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "enum": [ "items" ] } }, "in": "query", "name": "include", "required": false, "description": "`items`: the raw AJPES line items (Growth plan and up)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "19000006" }, "in": "path", "name": "tax_number", "required": true, "description": "Slovenian tax number (8 digits); an `SI` prefix, spaces and dots are accepted." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityFinancials" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/privacy/objections": { "post": { "operationId": "submitPrivacyObjection", "summary": "Object to name search (s.p. opt-out) or file a data-subject request", "tags": [ "Privacy" ], "description": "Public, no API key; rate-limited per IP. Stores the request and emails a confirmation link (valid 72 h). Always answers 202 for a well-formed request, whether or not the tax number exists. See maticna.si/zasebnost/podjetniki.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectionRequestInput" } } } }, "security": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectionAccepted" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/privacy/objections/confirm": { "get": { "operationId": "confirmPrivacyObjection", "summary": "Confirm a privacy request (emailed link)", "tags": [ "Privacy" ], "description": "Verifies the request. For a sole proprietor the name-search opt-out is applied immediately (`applied`); everything else goes to manual review (`in_review`). Browsers (Accept: text/html) are redirected back to the landing page.", "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 128 }, "in": "query", "name": "token", "required": true } ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectionConfirmed" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/changes": { "get": { "operationId": "listChanges", "summary": "Poll the change feed", "tags": [ "Changes" ], "description": "Changes detected in the FURS lists, oldest first, up to 1,000 per page (`limit`, default 100). Start with `since=` (Europe/Ljubljana) or an ISO 8601 timestamp, then always continue with `since=`: `next_cursor` is returned on every page, also an empty one, so store it and poll again later. Cursors do not expire with data refreshes. Filters: `types` (comma-separated change types) and `type` (entity type). Suppressed entities appear only as redacted events (no name, no values); `suppressed` events tell you to delete your copy. Natural persons count against the daily natural-person cap. 1 unit per page. Growth plan and up, scope `changes`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "example": "2026-10-19" }, "in": "query", "name": "since", "required": true, "description": "A `next_cursor` from an earlier page, or a start date `yyyy-mm-dd` (Europe/Ljubljana) or ISO 8601 timestamp (events detected at or after it)." }, { "schema": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] } }, "in": "query", "name": "types", "required": false, "description": "Comma-separated change types, e.g. `created,deactivated`." }, { "schema": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "in": "query", "name": "type", "required": false }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeList" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/entities/{tax_number}/history": { "get": { "operationId": "getEntityHistory", "summary": "Change history of one taxpayer", "tags": [ "Changes" ], "description": "Every change recorded for the tax number (all registrations), oldest first, paginated with `cursor`. History starts with the first daily sync after the initial load; dates already in the entity (VAT registration, revocations) are on the entity itself. A well-formed unknown tax number returns 404 (billable, like a lookup). 1 unit. Growth plan and up, scope `changes`.", "parameters": [ { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "19000006" }, "in": "path", "name": "tax_number", "required": true, "description": "Slovenian tax number (8 digits); an `SI` prefix, spaces and dots are accepted." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeList" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/monitors": { "get": { "operationId": "listMonitors", "summary": "List watched tax numbers", "tags": [ "Monitors" ], "description": "The org’s watchlist, ordered by tax number, with `slots` used and allowed by the plan. 0 units.", "parameters": [ { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorList" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createMonitor", "summary": "Watch a tax number", "tags": [ "Monitors" ], "description": "Adds a well-formed tax number to the watchlist (it does not have to be in the FURS lists yet: you then get `entity.created`). 201 when added, 200 when it was already watched. 403 `monitor_limit_reached` when the plan’s slots are full; 403 `plan_upgrade_required` on the Hobi plan (monitors are Starter and up). Changes are delivered to the org’s webhook endpoints (Starter+). 0 units.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_number": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Tax number to watch; `SI` prefix, spaces and dots are accepted.", "example": "19000006" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "tax_number" ] } } } }, "responses": { "200": { "description": "A watched tax number. Changes of every registration under it are delivered to the org’s webhook endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "monitor" ] }, "id": { "type": "string" }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "label": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "object", "id", "tax_number", "label", "created_at" ], "additionalProperties": false, "description": "A watched tax number. Changes of every registration under it are delivered to the org’s webhook endpoints." } } } }, "201": { "description": "A watched tax number. Changes of every registration under it are delivered to the org’s webhook endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "monitor" ] }, "id": { "type": "string" }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "label": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "object", "id", "tax_number", "label", "created_at" ], "additionalProperties": false, "description": "A watched tax number. Changes of every registration under it are delivered to the org’s webhook endpoints." } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/monitors/bulk": { "post": { "operationId": "bulkMonitors", "summary": "Add and remove up to 1,000 monitors", "tags": [ "Monitors" ], "description": "Removals run first, then additions. Additions are all-or-nothing against the slot limit (403 `monitor_limit_reached`, nothing added; Hobi: 403 `plan_upgrade_required`, removals only). Per-item `result`: added, exists, removed, not_monitored or invalid. 0 units.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "add": { "default": [], "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "remove": { "default": [], "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "label": { "description": "Label for the added monitors.", "type": "string", "minLength": 1, "maxLength": 200 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "monitor_bulk_result" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "action": { "type": "string", "enum": [ "add", "remove" ] }, "result": { "type": "string", "enum": [ "added", "exists", "removed", "not_monitored", "invalid" ] }, "tax_number": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$" }, { "type": "null" } ] } }, "required": [ "input", "action", "result", "tax_number" ], "additionalProperties": false } }, "slots": { "type": "object", "properties": { "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "used", "limit" ], "additionalProperties": false } }, "required": [ "object", "data", "slots" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/monitors/{tax_number}": { "delete": { "operationId": "deleteMonitor", "summary": "Stop watching a tax number", "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "19000006" }, "in": "path", "name": "tax_number", "required": true, "description": "Slovenian tax number (8 digits); an `SI` prefix, spaces and dots are accepted." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "monitor" ] }, "tax_number": { "type": "string", "pattern": "^\\d{8}$" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "object", "tax_number", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] }, "description": "Change types delivered; empty = all." }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "user", "consecutive_failures", "plan_downgraded" ] }, { "type": "null" } ], "description": "`user`: disabled by you. `consecutive_failures`: 20 failed attempts in a row. `plan_downgraded`: the plan no longer includes webhooks; the endpoint is re-enabled automatically after an upgrade (events from the downgraded period are not replayed)." }, "secret_hint": { "type": "string", "description": "Last 4 characters of the signing secret.", "example": "whsec_…k3Xa" }, "previous_secret_expires_at": { "description": "After a secret roll: until when events are also signed with the previous secret (a second `v1,` signature). null when there is none.", "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "url", "description", "event_types", "enabled", "disabled_reason", "secret_hint", "previous_secret_expires_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "An HTTPS endpoint that receives signed events for the org’s monitored entities." } }, "has_more": { "type": "boolean", "enum": [ false ] }, "next_cursor": { "type": "null" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "description": "Registers a public `https://` URL that receives signed events (Standard Webhooks) for the org’s monitored tax numbers. The `whsec_…` `secret` is returned **only in this response**: store it to verify `webhook-signature`. Optional `event_types` filter (change types). At most 10 endpoints per org. Starter plan and up, scope `webhooks`. 0 units.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "HTTPS URL that receives POSTed events.", "example": "https://example.com/hooks/maticna" }, "description": { "type": "string", "maxLength": 500 }, "event_types": { "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] } } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true, "description": "Webhook endpoint id (uuid)." } ], "responses": { "200": { "description": "An HTTPS endpoint that receives signed events for the org’s monitored entities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] }, "description": "Change types delivered; empty = all." }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "user", "consecutive_failures", "plan_downgraded" ] }, { "type": "null" } ], "description": "`user`: disabled by you. `consecutive_failures`: 20 failed attempts in a row. `plan_downgraded`: the plan no longer includes webhooks; the endpoint is re-enabled automatically after an upgrade (events from the downgraded period are not replayed)." }, "secret_hint": { "type": "string", "description": "Last 4 characters of the signing secret.", "example": "whsec_…k3Xa" }, "previous_secret_expires_at": { "description": "After a secret roll: until when events are also signed with the previous secret (a second `v1,` signature). null when there is none.", "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "url", "description", "event_types", "enabled", "disabled_reason", "secret_hint", "previous_secret_expires_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "An HTTPS endpoint that receives signed events for the org’s monitored entities." } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update or re-enable a webhook endpoint", "tags": [ "Webhooks" ], "description": "Change the URL, description or event types, or set `enabled`. Re-enabling an endpoint that was disabled after repeated failures resets the failure count; events from the disabled period are not replayed. Disabling (`{\"enabled\": false}` alone) also works on a plan without webhooks, e.g. after a downgrade.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "HTTPS URL that receives POSTed events.", "example": "https://example.com/hooks/maticna" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "event_types": { "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] } }, "enabled": { "description": "Re-enabling resets the failure counter; events missed while disabled are not replayed.", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true, "description": "Webhook endpoint id (uuid)." } ], "responses": { "200": { "description": "An HTTPS endpoint that receives signed events for the org’s monitored entities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "created", "updated", "deactivated", "reactivated", "vat_registered", "vat_deregistered", "vat_revoked", "suppressed" ] }, "description": "Change types delivered; empty = all." }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "user", "consecutive_failures", "plan_downgraded" ] }, { "type": "null" } ], "description": "`user`: disabled by you. `consecutive_failures`: 20 failed attempts in a row. `plan_downgraded`: the plan no longer includes webhooks; the endpoint is re-enabled automatically after an upgrade (events from the downgraded period are not replayed)." }, "secret_hint": { "type": "string", "description": "Last 4 characters of the signing secret.", "example": "whsec_…k3Xa" }, "previous_secret_expires_at": { "description": "After a secret roll: until when events are also signed with the previous secret (a second `v1,` signature). null when there is none.", "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "url", "description", "event_types", "enabled", "disabled_reason", "secret_hint", "previous_secret_expires_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "An HTTPS endpoint that receives signed events for the org’s monitored entities." } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "description": "Also works on a plan without webhooks (e.g. after a downgrade).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true, "description": "Webhook endpoint id (uuid)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "object", "id", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{id}/test": { "post": { "operationId": "sendTestWebhook", "summary": "Send a signed test event", "tags": [ "Webhooks" ], "description": "Queues a `webhook.test` event to the endpoint (delivered within about a minute, same signing and retries as real events). The response `id` is the `webhook-id` it is sent with.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true, "description": "Webhook endpoint id (uuid)." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "id": { "type": "string", "description": "The `webhook-id` the test event is sent with." }, "event_type": { "type": "string", "enum": [ "webhook.test" ] }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "object", "id", "event_type", "status" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{id}/roll-secret": { "post": { "operationId": "rollWebhookSecret", "summary": "Roll the signing secret", "tags": [ "Webhooks" ], "description": "Generates a new `whsec_…` secret, returned **only in this response**. The previous secret stays valid for `grace_period_hours` (default 24, at most 168; 0 retires it at once): meanwhile every event carries two signatures in `webhook-signature` (`v1, v1,`), so a receiver verifying with either secret accepts it. Rolling again during a grace period retires the older secret at once. Pending retries are signed the same way. 0 units.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "grace_period_hours": { "default": 24, "description": "How long the previous secret keeps signing events next to the new one (0–168 hours, default 24). 0 retires it at once.", "type": "integer", "minimum": 0, "maximum": 168 } }, "description": "Optional; an empty body uses the default grace period." }, { "type": "null" } ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true, "description": "Webhook endpoint id (uuid)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found (billable for a well-formed lookup)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/autocomplete": { "get": { "operationId": "autocomplete", "summary": "Type-ahead over taxpayer names", "tags": [ "Search" ], "description": "Lean projection for search boxes. 0.25 units per request; debounce 150–250 ms. Publishable keys (`mk_pub_…`) are allowed from allow-listed origins.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "q", "required": true }, { "schema": { "type": "string", "enum": [ "legal_entity", "sole_proprietor", "other_self_employed" ] }, "in": "query", "name": "type", "required": false }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 10 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutocompleteItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "data_as_of": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor", "data_as_of" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/vat/validate/{vat_id}": { "get": { "operationId": "validateVatId", "summary": "Validate a Slovenian VAT ID", "tags": [ "Validation" ], "description": "Checksum plus \"registered SI VAT payer as of `data_as_of`\", scope, VAT group and revocations. For natural persons who are VAT payers without a business registration, `entity_ref` is null and no name is returned.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "SI19000006" }, "in": "path", "name": "vat_id", "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatCheck" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tax-number/validate/{tax_number}": { "get": { "operationId": "validateTaxNumber", "summary": "Validate a Slovenian tax number", "tags": [ "Validation" ], "description": "mod-11 check digit plus presence in the FURS lists.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 32, "example": "19000006" }, "in": "path", "name": "tax_number", "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxNumberCheck" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/reference/{kind}": { "get": { "operationId": "getReferenceList", "summary": "Code lists", "tags": [ "Reference" ], "description": "SKD activity codes, tax offices, legal forms and postal codes. No key needed; never billed.", "parameters": [ { "schema": { "type": "string", "enum": [ "activity-codes", "tax-offices", "legal-forms", "postal-codes" ] }, "in": "path", "name": "kind", "required": true } ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceList" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/meta/status": { "get": { "operationId": "getStatus", "summary": "Data freshness and sync status", "tags": [ "Meta" ], "description": "Freshness per dataset, last run status, guard result and row counts. No key needed; never billed.", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaStatus" } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Current period usage and quota", "tags": [ "Meta" ], "description": "For the calling key and its organisation. Any key; never billed.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "Bad request (`bad_request`, `key_in_query_forbidden`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid, revoked or expired key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Insufficient scope, plan upgrade required, origin not allowed or a plan limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid identifier or query too short", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited, quota exceeded or natural-person cap exceeded (with `Retry-After`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "servers": [ { "url": "https://api.maticna.si", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Entities", "description": "Exact lookups by tax number, registration number or VAT ID." }, { "name": "Search", "description": "Name search, filtered listing and autocomplete." }, { "name": "Validation", "description": "VAT ID and tax number checks." }, { "name": "Reference", "description": "Code lists." }, { "name": "Meta", "description": "Status and usage." }, { "name": "Financials", "description": "AJPES annual-report financial statements of companies (CC BY 4.0; never for s.p.)." }, { "name": "Changes", "description": "Change feed and per-entity history (Growth plan and up)." }, { "name": "Monitors", "description": "Watchlist of tax numbers whose changes are delivered by webhook and e-mail alert (Starter and up; slots per plan, Hobi has none)." }, { "name": "Webhooks", "description": "Signed (Standard Webhooks) event delivery for monitored tax numbers (Starter plan and up)." } ] }