openapi: 3.0.3
info:
  title: FirmAPI
  description: |
    REST API for Slovak company data with enrichment layers and change notifications.

    ## Data Sources
    FirmAPI combines data from multiple Slovak registers and enrichment sources:
    - **RPO** (Register právnických osôb) - Base company data updated daily (1.2M+ entities)
    - **ORSR** (Obchodný register) - Detailed data for commercial register companies (shareholders, statutory bodies, business activities)
    - **Tax and financial sources** - Tax IDs (DIČ), VAT IDs (IČ DPH), VAT payer status, financial metrics, and financial statements
    - **EU VIES** - VAT ID validation
    - **Public registers and bulletins** - Debtor lists, insolvency, commercial bulletin, public contracts, and procurement data

    ## Stale Data & Background Refresh
    If ORSR detail data is older than 30 days, or enrichment data is older than 10 days, the API returns the latest available data immediately with `meta.stale: true` and `meta.retry_at` (ISO 8601 timestamp). A background refresh is queued automatically. Poll the same endpoint after `retry_at` for fresh data.

    ## Notifications
    FirmAPI supports change notifications through webhook URLs and email. Manage subscriptions through `/notifications` endpoints. Webhook deliveries include HMAC signature headers. Email deliveries are tracked in the same delivery history.

    ## Authentication
    All API requests require authentication using an API key. Include your API key in the `Authorization` header as a Bearer token or use the `X-API-Key` header.

    ## Rate Limits
    Rate limits depend on your subscription tier. Headers are included in all responses:
    - `X-RateLimit-Limit-Minute` - Requests allowed per minute
    - `X-RateLimit-Remaining-Minute` - Requests remaining this minute
    - `X-RateLimit-Limit-Daily` - Requests allowed per day
    - `X-RateLimit-Remaining-Daily` - Requests remaining today
  version: 1.0.0
  contact:
    name: FirmAPI Support
    email: support@firmapi.sk
    url: https://firmapi.sk
  license:
    name: Proprietary
    url: https://firmapi.sk/terms

servers:
  - url: https://api.firmapi.sk/v1
    description: Production API

security:
  - BearerAuth: []
  - ApiKeyAuth: []

tags:
  - name: Status
    description: API status and health checks
  - name: Company
    description: Company lookup endpoints
  - name: Search
    description: Search and autocomplete endpoints
  - name: Batch
    description: Batch lookup operations (Starter+ plans)
  - name: Account
    description: Account and usage information
  - name: Notifications
    description: Change subscriptions, delivery history, and test endpoints

paths:
  /status:
    get:
      tags:
        - Status
      summary: API Health Check
      description: Check API availability and status.
      security: []
      responses:
        '200':
          description: API is operational
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: '1.0.0'

  /company/ico/{ico}:
    get:
      tags:
        - Company
      summary: Get Company by IČO
      description: Retrieve company details by IČO (registration number).
      parameters:
        - name: ico
          in: path
          required: true
          description: 8-digit company registration number
          schema:
            type: string
            pattern: '^\d{8}$'
            example: '51636549'
        - name: scope
          in: query
          required: false
          description: >
            Comma-separated list of enrichment scopes to include.
            Omit for base data only (fastest). Use "all" for everything.
            Available: tax, bank_accounts, contacts, financials, debtor_status,
            financial_statements, insolvency, commercial_bulletin, public_contracts, procurement,
            execution_authorizations, rpvs, nbs, tax_reliability, erased_vat,
            reges, social_enterprise, gleif, sanctions, ted_tenders,
            replik_administrator, sbs, transport_licence, utility_licence,
            contracting_authority, debarred, uvo_references, fs_imports,
            illegal_employment, court_decisions, employer_headcount,
            soi_travel_agency, svps_establishments, crp_projects,
            trade_license_activities, registered_activities
          schema:
            type: string
            example: 'tax,financials,debtor_status'
      responses:
        '200':
          description: Company found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /company/id/{orsr_id}:
    get:
      tags:
        - Company
      summary: Get Company by ORSR ID
      description: Retrieve company details by ORSR internal ID.
      parameters:
        - name: orsr_id
          in: path
          required: true
          description: ORSR internal ID
          schema:
            type: string
            example: '427482'
        - name: scope
          in: query
          required: false
          description: Comma-separated enrichment scopes. Omit for base data only. Use "all" for everything.
          schema:
            type: string
            example: 'tax,financials'
      responses:
        '200':
          description: Company found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /company/{id}:
    get:
      tags:
        - Company
      summary: Get Company by Internal ID
      description: Retrieve company details by internal database ID.
      parameters:
        - name: id
          in: path
          required: true
          description: Internal database ID
          schema:
            type: integer
            example: 12345
        - name: scope
          in: query
          required: false
          description: Comma-separated enrichment scopes. Omit for base data only. Use "all" for everything.
          schema:
            type: string
            example: 'tax,financials'
      responses:
        '200':
          description: Company found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /search/autocomplete:
    get:
      tags:
        - Search
      summary: Autocomplete Search
      description: |
        Search companies by name or IČO with autocomplete.
        Returns Select2-compatible format.
      parameters:
        - name: q
          in: query
          required: true
          description: Search query (min 2 characters)
          schema:
            type: string
            minLength: 2
            example: 'version'
        - name: limit
          in: query
          description: Maximum results (default 10, max 20)
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 10
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /search/name:
    get:
      tags:
        - Search
      summary: Search by Name
      description: Search companies by name with pagination.
      parameters:
        - name: q
          in: query
          required: true
          description: Company name
          schema:
            type: string
            minLength: 3
            example: 'Version Two'
        - name: exact
          in: query
          description: Exact match (0 or 1)
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - name: limit
          in: query
          description: Maximum results
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /search/ico:
    get:
      tags:
        - Search
      summary: Search by Partial IČO
      description: Search companies by partial IČO number.
      parameters:
        - name: q
          in: query
          required: true
          description: Partial IČO
          schema:
            type: string
            example: '5163'
        - name: limit
          in: query
          description: Maximum results
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /search/advanced:
    get:
      tags:
        - Search
      summary: Advanced Search
      description: Multi-field search with various filters.
      parameters:
        - name: name
          in: query
          description: Company name
          schema:
            type: string
        - name: city
          in: query
          description: City name
          schema:
            type: string
        - name: legal_form
          in: query
          description: Legal form
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum results
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /batch/ico:
    post:
      tags:
        - Batch
      summary: Batch Lookup by IČO
      description: |
        Batch lookup of multiple companies by IČO.
        Requires Starter plan or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - icos
              properties:
                icos:
                  type: array
                  items:
                    type: string
                    pattern: '^\d{8}$'
                  minItems: 1
                  maxItems: 100
                  example: ['51636549', '12345678', '87654321']
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /batch/names:
    post:
      tags:
        - Batch
      summary: Batch Lookup by Names
      description: |
        Batch lookup of multiple companies by name.
        Requires Starter plan or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - names
              properties:
                names:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
                  example: ['Version Two s. r. o.', 'Example Company']
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /batch/{batchId}/status:
    get:
      tags:
        - Batch
      summary: Get Batch Status
      description: Get the status of a batch job.
      parameters:
        - name: batchId
          in: path
          required: true
          description: Batch job ID
          schema:
            type: string
      responses:
        '200':
          description: Batch status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /batch/{batchId}/results:
    get:
      tags:
        - Batch
      summary: Get Batch Results
      description: Get the results of a completed batch job.
      parameters:
        - name: batchId
          in: path
          required: true
          description: Batch job ID
          schema:
            type: string
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /account/usage:
    get:
      tags:
        - Account
      summary: Get Usage Statistics
      description: Get current period usage statistics.
      responses:
        '200':
          description: Usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /account/quota:
    get:
      tags:
        - Account
      summary: Get Remaining Quota
      description: Get remaining quota for current period.
      responses:
        '200':
          description: Quota information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /account/history:
    get:
      tags:
        - Account
      summary: Get Usage History
      description: Get usage history for the specified period.
      parameters:
        - name: days
          in: query
          description: Number of days to retrieve
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
      responses:
        '200':
          description: Usage history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /notifications:
    get:
      tags:
        - Notifications
      summary: List notification subscriptions
      description: List webhook/email notification subscriptions for the authenticated API user.
      responses:
        '200':
          description: Subscription list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSubscriptionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - Notifications
      summary: Create or update notification subscription
      description: Create or update a company change subscription with a webhook URL, an email destination, or both.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSubscriptionCreateRequest'
      responses:
        '201':
          description: Subscription created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSubscriptionCreateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'

  /notifications/{ico}:
    delete:
      tags:
        - Notifications
      summary: Delete notification subscription
      description: Delete the subscription for the specified company IČO.
      parameters:
        - name: ico
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{8}$'
            example: '51636549'
      responses:
        '200':
          description: Subscription deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Webhook subscription deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /notifications/{subscriptionId}/deliveries:
    get:
      tags:
        - Notifications
      summary: Get delivery history
      description: Retrieve the most recent webhook/email deliveries for a specific subscription.
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: integer
            example: 42
      responses:
        '200':
          description: Delivery history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationDeliveryListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /notifications/history/{ico}:
    get:
      tags:
        - Notifications
      summary: Get company change history
      description: Retrieve detected company changes for a specific IČO.
      parameters:
        - name: ico
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{8}$'
            example: '51636549'
      responses:
        '200':
          description: Company change history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationHistoryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /notifications/test:
    post:
      tags:
        - Notifications
      summary: Validate notification destination
      description: Validate a webhook URL or email destination without creating a persistent subscription.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type: string
                  format: uri
                  nullable: true
                  example: https://example.com/firmapi/webhook
                notification_emails:
                  type: array
                  nullable: true
                  maxItems: 25
                  items:
                    type: string
                    format: email
                  example:
                    - ops@example.com
                    - alerts@example.com
                notification_email:
                  type: string
                  format: email
                  nullable: true
                  deprecated: true
                  description: |
                    Deprecated. Send `notification_emails` (an array) instead. When
                    only `notification_email` is supplied it is transparently promoted
                    to `notification_emails: [<email>]`. Responses include
                    `Deprecation: true` and a `Sunset` header in this case.
                  example: ops@example.com
      responses:
        '200':
          description: Destination validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer YOUR_API_KEY'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'X-API-Key: YOUR_API_KEY'

  schemas:
    Company:
      type: object
      properties:
        ico:
          type: string
          description: 8-digit company registration number
          example: '51636549'
        name:
          type: string
          example: 'Version Two s. r. o.'
        legal_form:
          type: string
          description: Legal form name (from RPO)
          example: 'Spoločnosť s ručením obmedzeným'
        legal_form_code:
          type: string
          nullable: true
          description: Legal form numeric code (from RPO registry)
          example: '112'
        address:
          type: object
          description: Structured address from RPO
          properties:
            street:
              type: string
              example: 'Hlavná 1'
            city:
              type: string
              example: 'Bratislava'
            postal_code:
              type: string
              example: '81101'
            country:
              type: string
              example: 'Slovensko'
        established_date:
          type: string
          format: date
          nullable: true
          example: '2018-05-15'
        terminated_date:
          type: string
          format: date
          nullable: true
          example: null
        source_register:
          type: string
          description: Source register name (e.g. "Obchodný register", "Živnostenský register")
          example: 'Obchodný register'
        status:
          type: string
          enum: [active, terminated, deleted]
          example: 'active'
        nace_code:
          type: string
          nullable: true
          description: SK NACE classification code (from RPO). Only present when scope=all is served from a precomputed profile with nace_code set.
          example: '62.01'
        nace_description:
          type: string
          nullable: true
          description: SK NACE classification description (from RPO). Only present when scope=all is served from a precomputed profile with nace_code set.
          example: 'Počítačové programovanie'
        orsr_id:
          type: string
          nullable: true
          description: ORSR internal ID (only for commercial register companies)
          example: '427482'
        registration_date:
          type: string
          format: date
          nullable: true
          description: ORSR registration date (from ORSR.sk detail page)
          example: '2018-05-15'
        business_activities:
          type: array
          description: Business activities from ORSR.sk (only for commercial register companies). One entry per "Predmet podnikania" line, with the date it became effective.
          items:
            type: object
            properties:
              activity:
                type: string
                example: 'Počítačové služby'
              since:
                type: string
                format: date
                nullable: true
                example: '2013-10-01'
        trade_license_activities:
          type: array
          description: Trade-license (živnostenský register) activities for sole traders. Present only when ZRSR enrichment has data for the IČO.
          items:
            type: object
            properties:
              activity:
                type: string
                example: 'Reklamné a marketingové služby'
              kind:
                type: string
                enum: ['voľná', 'remeselná', 'viazaná']
                example: 'voľná'
              effective_from:
                type: string
                format: date
                nullable: true
                example: '2013-10-01'
              effective_to:
                type: string
                format: date
                nullable: true
              authority:
                type: string
                nullable: true
        registered_activities:
          type: array
          description: >-
            Predmety podnikania as recorded in the Register právnických osôb (RPO V2),
            covering every source register – živnostenský, obchodný, občianske združenia
            and the rest. Wider coverage than both `business_activities` (ORSR) and
            `trade_license_activities` (ZRSR), and the only source that carries
            suspension dates. Present only when RPO holds activities for the IČO.
          items:
            type: object
            properties:
              activity:
                type: string
                example: 'Počítačové služby a služby súvisiace s počítačovým spracovaním údajov'
              effective_from:
                type: string
                format: date
                nullable: true
                example: '2016-07-11'
              effective_to:
                type: string
                format: date
                nullable: true
              suspended_from:
                type: string
                format: date
                nullable: true
                description: Start of a pozastavenie (suspension), when one applies.
                example: '2023-03-28'
              suspended_to:
                type: string
                format: date
                nullable: true
                example: '2030-03-28'
              source_register:
                type: string
                nullable: true
                example: 'Živnostenský register'
              authority:
                type: string
                nullable: true
                example: 'Okresný úrad Bratislava'
        illegal_employment:
          type: object
          description: National Labour Inspectorate – illegal-employment register snapshot (always present, even when not listed).
          properties:
            listed:
              type: boolean
            count:
              type: integer
            since:
              type: string
              format: date
              nullable: true
            entries:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  address:
                    type: string
                    nullable: true
                  violation_date:
                    type: string
                    format: date
                    nullable: true
                  decision_date:
                    type: string
                    format: date
                    nullable: true
                  decision_number:
                    type: string
                    nullable: true
        court_decisions:
          type: object
          description: Aggregated court decisions from otvorenesudy.sk where the company is listed as a party. Always present (total=0, recent=[] when no records exist).
          properties:
            total:
              type: integer
            last_5_years:
              type: integer
            recent:
              type: array
              description: Up to 25 most recent decisions.
              items:
                type: object
                properties:
                  decision_date:
                    type: string
                    format: date
                    nullable: true
                  court:
                    type: string
                    nullable: true
                  case_number:
                    type: string
                    nullable: true
                  role:
                    type: string
                    nullable: true
                    enum: [plaintiff, defendant, other]
                  ruling:
                    type: string
                    nullable: true
                    enum: [won, lost, partial, procedural, unknown]
                  decision_type:
                    type: string
                    nullable: true
                  pdf_url:
                    type: string
                    nullable: true
        employer_headcount:
          type: object
          nullable: true
          description: Headcount bracket from the Sociálna poisťovňa employer registry. Key is always present when the scope is requested; value is null when the company is not currently registered as an employer.
          properties:
            name:
              type: string
            bracket:
              type: string
              example: '50-249'
            registered_at:
              type: string
              format: date
              nullable: true
            deregistered_at:
              type: string
              format: date
              nullable: true
        soi_travel_agency:
          type: object
          nullable: true
          description: SOI travel-agency register entry incl. insolvency cover. Always present when the scope is requested ({is_registered=false} when the company is not in the register).
          properties:
            is_registered:
              type: boolean
            name:
              type: string
            address:
              type: string
              nullable: true
            insolvency_provider:
              type: string
              nullable: true
            insolvency_amount:
              type: number
              nullable: true
            insolvency_valid_from:
              type: string
              format: date
              nullable: true
            insolvency_valid_to:
              type: string
              format: date
              nullable: true
            has_ban:
              type: boolean
        svps_establishments:
          type: array
          description: ŠVPS approved food/veterinary establishments matched to the company.
          items:
            type: object
            properties:
              approval_number:
                type: string
              register_type:
                type: string
                enum: [food, vet]
              section_code:
                type: string
                nullable: true
              section_label:
                type: string
                nullable: true
              activity_code:
                type: string
                nullable: true
              activity_label:
                type: string
                nullable: true
              name:
                type: string
              city:
                type: string
                nullable: true
              district:
                type: string
                nullable: true
              region:
                type: string
                nullable: true
              match_confidence:
                type: number
                nullable: true
              match_method:
                type: string
                nullable: true
        registered_capital:
          type: string
          nullable: true
          description: Registered capital (only for commercial register companies)
          example: '5 000 EUR'
        shareholders:
          type: array
          description: Company shareholders (only for commercial register companies, from ORSR.sk)
          items:
            $ref: '#/components/schemas/Shareholder'
        statutory_body:
          type: array
          description: Statutory body members (only for commercial register companies, from ORSR.sk)
          items:
            $ref: '#/components/schemas/StatutoryBody'
        tax:
          $ref: '#/components/schemas/TaxInfo'
        bank_accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankAccount'
        contacts:
          $ref: '#/components/schemas/Contacts'
        financials:
          $ref: '#/components/schemas/Financials'
        debtor_status:
          type: object
          nullable: true
          additionalProperties: true
          description: Debtor list status summary when enabled for the current plan
        financial_statements:
          $ref: '#/components/schemas/FinancialStatements'
        insolvency:
          $ref: '#/components/schemas/Insolvency'
        execution_authorizations:
          $ref: '#/components/schemas/ExecutionAuthorizationsInfo'
        commercial_bulletin:
          $ref: '#/components/schemas/CommercialBulletin'
        public_contracts_summary:
          type: object
          nullable: true
          additionalProperties: true
          description: Public contracts summary when enabled for the current plan
        procurement_summary:
          type: object
          nullable: true
          additionalProperties: true
          description: Procurement summary when enabled for the current plan
        rpvs:
          $ref: '#/components/schemas/RpvsInfo'
        nbs:
          $ref: '#/components/schemas/NbsInfo'
        tax_reliability:
          $ref: '#/components/schemas/TaxReliabilityInfo'
        erased_vat:
          $ref: '#/components/schemas/ErasedVatInfo'
        reges:
          $ref: '#/components/schemas/RegesInfo'
        social_enterprise:
          $ref: '#/components/schemas/SocialEnterpriseInfo'
        gleif:
          $ref: '#/components/schemas/GleifInfo'
        sanctions:
          $ref: '#/components/schemas/SanctionsInfo'
        ted_tenders:
          $ref: '#/components/schemas/TedTendersInfo'
        replik_administrator:
          $ref: '#/components/schemas/ReplikAdministratorInfo'
        sbs:
          $ref: '#/components/schemas/SbsInfo'
        transport_licence:
          $ref: '#/components/schemas/TransportLicenceInfo'
        utility_licence:
          $ref: '#/components/schemas/UtilityLicenceInfo'
        contracting_authority:
          $ref: '#/components/schemas/ContractingAuthorityInfo'
        debarred:
          $ref: '#/components/schemas/DebarredInfo'
        uvo_references:
          $ref: '#/components/schemas/UvoReferencesInfo'
        crp_projects:
          $ref: '#/components/schemas/CrpProjectsInfo'
        fs:
          $ref: '#/components/schemas/FsData'

    Shareholder:
      type: object
      properties:
        name:
          type: string
          example: 'John Doe'
        address:
          type: string
          example: 'Bratislava'
        share_amount:
          type: string
          example: '5000 EUR'
        share_percentage:
          type: string
          example: '100%'
        is_company:
          type: boolean
          description: Whether the shareholder is a legal entity
          example: false
        ico:
          type: string
          nullable: true
          description: IČO of the shareholder if it is a legal entity
          example: null

    StatutoryBody:
      type: object
      properties:
        name:
          type: string
          example: 'John Doe'
        role:
          type: string
          example: 'konateľ'
        address:
          type: string
          example: 'Bratislava'
        acting_method:
          type: string
          nullable: true
          description: Method of acting on behalf of the company
          example: 'samostatne'

    TaxInfo:
      type: object
      description: Available on Starter+ plans
      properties:
        dic:
          type: string
          example: '2120123456'
        ic_dph:
          type: string
          example: 'SK2120123456'
        vies_valid:
          type: boolean
          example: true
        vies_verified_at:
          type: string
          format: date-time
          example: '2024-01-15T10:00:00Z'
        is_vat_payer:
          type: boolean
          description: Whether the company is a registered VAT payer
          example: true

    BankAccount:
      type: object
      description: Available on Professional+ plans
      properties:
        iban:
          type: string
          example: 'SK89 1100 0000 0012 3456 7890'
        bank_name:
          type: string
          example: 'Tatra banka'
        is_published:
          type: boolean
          example: true

    Contacts:
      type: object
      description: Available on Professional+ plans. Keys are contact types, values are arrays of strings.
      additionalProperties:
        type: array
        items:
          type: string
      example:
        email: ['info@versiontwo.sk']
        phone: ['+421 2 1234 5678']
        website: ['https://versiontwo.sk']

    Financials:
      type: object
      description: Available on Enterprise plan only
      properties:
        year:
          type: integer
          example: 2023
        revenue:
          type: number
          example: 150000
        profit:
          type: number
          example: 25000
        assets:
          type: number
          example: 200000
        employees_count:
          type: integer
          example: 5

    FinancialStatements:
      type: object
      nullable: true
      description: Available when the financial statements feature is enabled
      properties:
        latest:
          type: object
          nullable: true
          properties:
            year:
              type: integer
              example: 2023
            statement_type:
              type: string
              example: riadna
            total_assets:
              type: number
              example: 250000
            total_equity:
              type: number
              example: 80000
            total_liabilities:
              type: number
              example: 170000
            total_revenue:
              type: number
              example: 190000
            net_profit:
              type: number
              example: 22000
            template_type:
              type: string
              example: micro
            size_category:
              type: string
              example: small
        statements:
          type: array
          description: >-
            Full multi-year series ordered by fiscal year (newest first).
            Enables revenue/profit/equity charting across years.
          items:
            type: object
            properties:
              year:
                type: integer
                example: 2023
              statement_type:
                type: string
                example: riadna
              total_assets:
                type: number
                example: 250000
              total_equity:
                type: number
                example: 80000
              total_liabilities:
                type: number
                example: 170000
              total_revenue:
                type: number
                example: 190000
              net_profit:
                type: number
                example: 22000
              template_type:
                type: string
                example: micro
              size_category:
                type: string
                example: small
        available_years:
          type: array
          items:
            type: integer
          example: [2021, 2022, 2023]

    Insolvency:
      type: object
      nullable: true
      properties:
        has_active_proceedings:
          type: boolean
          example: false
        proceedings:
          type: array
          items:
            type: object
            properties:
              case_number:
                type: string
                example: 8K/12/2025
              proceeding_type:
                type: string
                example: bankruptcy
              status:
                type: string
                example: active
              court:
                type: string
                example: Okresny sud Bratislava I
              administrator:
                type: string
                nullable: true
                example: Spravca, k.s.
              started_at:
                type: string
                format: date
                nullable: true
                example: '2025-09-01'

    CommercialBulletin:
      type: object
      nullable: true
      properties:
        total_entries:
          type: integer
          example: 3
        latest_entries:
          type: array
          items:
            type: object
            properties:
              section:
                type: string
                example: Konkurzy a restrukturalizacie
              heading:
                type: string
                example: Zverejnenie uznesenia
              published_at:
                type: string
                format: date
                nullable: true
                example: '2026-02-12'

    CompanyResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Company'
        meta:
          type: object
          properties:
            rpo_updated_at:
              type: string
              format: date-time
              description: When RPO data was last updated
              example: '2024-01-15T06:00:00Z'
            orsr_synced_at:
              type: string
              format: date-time
              nullable: true
              description: When ORSR detail data was last fetched
              example: '2024-01-10T14:30:00Z'
            enriched_at:
              type: string
              format: date-time
              nullable: true
              description: When enrichment data was last refreshed
              example: '2024-01-15T10:00:00Z'
            source:
              type: string
              example: 'database'
            cached:
              type: boolean
              description: Present when the response was served from cache
              example: true
            stale:
              type: boolean
              description: Whether ORSR detail or enrichment data is outdated or not yet available
              example: false
            retry_at:
              type: string
              format: date-time
              nullable: true
              description: When to retry for fresh data (only present when stale=true). A background refresh has been queued automatically.
              example: '2024-01-15T10:30:15Z'
            stale_reason:
              type: string
              nullable: true
              description: Reason for staleness
              enum: [orsr_data_not_available, orsr_data_outdated, enrichment_data_not_available, enrichment_data_outdated, orsr_and_enrichment_data_stale]
              example: null

    NotificationSubscription:
      type: object
      properties:
        id:
          type: integer
          example: 42
        ico:
          type: string
          example: '51636549'
        webhook_url:
          type: string
          format: uri
          nullable: true
          example: https://example.com/firmapi/webhook
        notification_emails:
          type: array
          nullable: true
          maxItems: 25
          items:
            type: string
            format: email
          example:
            - ops@example.com
            - alerts@example.com
        notification_email:
          type: string
          format: email
          nullable: true
          deprecated: true
          description: |
            Deprecated read alias. Equals the first entry of `notification_emails`
            (or null when empty). Old SDKs that read this field continue to work
            until the documented sunset date; new integrations MUST use
            `notification_emails`.
          example: ops@example.com
        secret:
          type: string
          nullable: true
          example: 2f95a2f3a68f4c7f9d9f4d6f4d8f8b0c
        events:
          type: array
          nullable: true
          description: |
            Webhook event names. Null/empty array means subscribe to all events.
            See `WebhookSubscription::SUPPORTED_EVENTS` in the codebase for the
            authoritative list. Events are grouped into `company`, `risk`, and
            `public` buckets surfaced via the dashboard UI.
          items:
            type: string
            enum:
              - company.created
              - company.updated
              - company.deleted
              - orsr.updated
              - tax.updated
              - vat.updated
              - activity.added
              - activity.removed
              - activity.suspended
              - activity.resumed
              - debtor.added
              - debtor.removed
              - financial_statement.published
              - insolvency.updated
              - execution_authorization.updated
              - public_sector_partner.updated
              - commercial_bulletin.published
              - public_contract.published
              - procurement.published
              - qualified_supplier.updated
              - social_enterprise.updated
              - gleif.updated
              - sanctions.match
              - ted_tender.published
              - insolvency_administrator.updated
              - sbs_licence.updated
              - transport_licence.updated
              - utility_licence.updated
        is_active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          example: '2026-03-08T10:00:00Z'

    NotificationSubscriptionCreateRequest:
      type: object
      required:
        - ico
      properties:
        ico:
          type: string
          pattern: '^\d{8}$'
          example: '51636549'
        webhook_url:
          type: string
          format: uri
          nullable: true
          example: https://example.com/firmapi/webhook
        notification_emails:
          type: array
          nullable: true
          maxItems: 25
          description: One or more recipient emails. Each enabled address receives its own delivery row.
          items:
            type: string
            format: email
          example:
            - ops@example.com
            - alerts@example.com
        notification_email:
          type: string
          format: email
          nullable: true
          deprecated: true
          description: |
            Deprecated request alias for backward compatibility with v1.x SDKs.
            If supplied without `notification_emails` it is promoted to
            `notification_emails: [<email>]`. Responses to such requests include
            `Deprecation: true` and a `Sunset` header.
          example: ops@example.com
        events:
          type: array
          nullable: true
          description: |
            Webhook event names. Null/empty array means subscribe to all events.
            See `WebhookSubscription::SUPPORTED_EVENTS` in the codebase for the
            authoritative list. Events are grouped into `company`, `risk`, and
            `public` buckets surfaced via the dashboard UI.
          items:
            type: string
            enum:
              - company.created
              - company.updated
              - company.deleted
              - orsr.updated
              - tax.updated
              - vat.updated
              - activity.added
              - activity.removed
              - activity.suspended
              - activity.resumed
              - debtor.added
              - debtor.removed
              - financial_statement.published
              - insolvency.updated
              - execution_authorization.updated
              - public_sector_partner.updated
              - commercial_bulletin.published
              - public_contract.published
              - procurement.published
              - qualified_supplier.updated
              - social_enterprise.updated
              - gleif.updated
              - sanctions.match
              - ted_tender.published
              - insolvency_administrator.updated
              - sbs_licence.updated
              - transport_licence.updated
              - utility_licence.updated

    NotificationSubscriptionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NotificationSubscription'
        meta:
          type: object
          properties:
            total:
              type: integer
              example: 4
            per_page:
              type: integer
              example: 50
            current_page:
              type: integer
              example: 1

    NotificationSubscriptionCreateResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/NotificationSubscription'
        message:
          type: string
          example: Webhook subscription created successfully

    NotificationDelivery:
      type: object
      properties:
        id:
          type: integer
          example: 1001
        channel:
          type: string
          enum: [webhook, email]
          example: webhook
        target:
          type: string
          example: https://example.com/firmapi/webhook
        status:
          type: string
          example: delivered
        http_status:
          type: integer
          nullable: true
          example: 200
        response_time_ms:
          type: integer
          nullable: true
          example: 182
        attempt_count:
          type: integer
          example: 1
        created_at:
          type: string
          format: date-time
          example: '2026-03-08T10:05:00Z'

    NotificationDeliveryListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NotificationDelivery'

    NotificationHistoryItem:
      type: object
      properties:
        id:
          type: integer
          example: 77
        change_type:
          type: string
          example: updated
        field:
          type: string
          nullable: true
          example: address
        old_value:
          nullable: true
          example: Hlavna 1, Bratislava
        new_value:
          nullable: true
          example: Mlynske nivy 5, Bratislava
        detected_at:
          type: string
          format: date-time
          example: '2026-03-08T09:00:00Z'
        source:
          type: string
          nullable: true
          example: orsr

    NotificationHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NotificationHistoryItem'
        meta:
          type: object
          properties:
            ico:
              type: string
              example: '51636549'
            total_changes:
              type: integer
              example: 3

    NotificationTestResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Validation passed. Use the dashboard test flow for end-to-end delivery checks.
        destinations:
          type: object
          properties:
            webhook_url:
              type: string
              format: uri
              nullable: true
              example: https://example.com/firmapi/webhook
            notification_emails:
              type: array
              nullable: true
              items:
                type: string
                format: email
              example:
                - ops@example.com
            notification_email:
              type: string
              format: email
              nullable: true
              deprecated: true
              description: Deprecated read alias. Equals the first `notification_emails` entry.
              example: ops@example.com

    AutocompleteResult:
      type: object
      properties:
        id:
          type: string
          example: '51636549'
        text:
          type: string
          example: 'Version Two s. r. o.'
        ico:
          type: string
          example: '51636549'
        city:
          type: string
          example: 'Bratislava'

    AutocompleteResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AutocompleteResult'
        pagination:
          type: object
          properties:
            more:
              type: boolean
              example: false

    SearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Company'
        meta:
          type: object
          properties:
            total:
              type: integer
              example: 25
            limit:
              type: integer
              example: 10
            offset:
              type: integer
              example: 0

    BatchResult:
      type: object
      properties:
        found:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Company'

    BatchResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BatchResult'
          example:
            '51636549':
              found: true
              data: {}
            '12345678':
              found: false
              data: null
        meta:
          type: object
          properties:
            total:
              type: integer
              example: 3
            found:
              type: integer
              example: 2
            not_found:
              type: integer
              example: 1

    BatchStatusResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              example: 'batch-123'
            status:
              type: string
              enum: [pending, processing, completed, failed]
              example: 'completed'
            total:
              type: integer
              example: 10
            processed:
              type: integer
              example: 10
            created_at:
              type: string
              format: date-time
            completed_at:
              type: string
              format: date-time

    UsageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            requests_today:
              type: integer
              example: 45
            requests_month:
              type: integer
              example: 350
            limit_daily:
              type: integer
              example: 100
            limit_monthly:
              type: integer
              example: 1000

    QuotaResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            remaining_daily:
              type: integer
              example: 55
            remaining_monthly:
              type: integer
              example: 650
            reset_daily:
              type: string
              format: date-time
              example: '2024-01-16T00:00:00Z'
            reset_monthly:
              type: string
              format: date-time
              example: '2024-02-01T00:00:00Z'

    HistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                example: '2024-01-15'
              requests:
                type: integer
                example: 45

    Error:
      type: object
      properties:
        error:
          type: string
          example: 'not_found'
        message:
          type: string
          example: 'Company not found'

    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: 'validation_error'
        message:
          type: string
          example: 'The given data was invalid.'
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            ico:
              - 'The ico must be 8 digits.'

    ExecutionAuthorizationsInfo:
      type: object
      nullable: true
      description: >
        Poverenia na vykonanie exekúcie (register poverení na vykonanie exekúcie).
        Dostupné pre plány s funkciou execution_authorizations.
      properties:
        has_active_authorizations:
          type: boolean
          description: Či má subjekt aktuálne aktívne poverenie na vykonanie exekúcie
          example: true
        total_count:
          type: integer
          description: Celkový počet aktívnych poverení
          example: 1
        authorizations:
          type: array
          items:
            type: object
            properties:
              ecli:
                type: string
                nullable: true
                example: 'ECLI:SK:OSBA1:2024:1234'
              court_file_number:
                type: string
                nullable: true
                example: '10Er/100/2024'
              court:
                type: string
                nullable: true
                example: 'Okresný súd Bratislava I'
              executor_name:
                type: string
                nullable: true
                example: 'JUDr. Ján Novák'
              enforced_claim:
                type: string
                nullable: true
                example: 'Peňažná pohľadávka 5000 EUR'
              creditors:
                type: array
                description: Zoznam veriteľov (surová JSON štruktúra)
                items:
                  type: object
                  additionalProperties: true
                example: [{ "name": "Creditor s.r.o." }]
              authorized_at:
                type: string
                format: date
                nullable: true
                example: '2024-06-15'
              published_at:
                type: string
                format: date
                nullable: true
                example: '2024-06-20'

    RpvsInfo:
      type: object
      nullable: true
      description: >
        Register partnerov verejného sektora (RPVS) – aktívne registrácie.
        Dostupné pre plány s funkciou rpvs.
      properties:
        is_public_sector_partner:
          type: boolean
          description: Či je subjekt aktuálne registrovaný ako partner verejného sektora
          example: true
        registrations:
          type: array
          items:
            type: object
            properties:
              business_name:
                type: string
                example: 'Test Company s.r.o.'
              person_type:
                type: string
                example: 'PO'
              valid_from:
                type: string
                format: date
                nullable: true
                example: '2023-01-01'
              beneficial_owners:
                type: array
                description: Zoznam konečných užívateľov výhod (surová JSON štruktúra)
                items:
                  type: object
                  additionalProperties: true
                example: [{ "name": "Ján Novák", "share": "50%" }]

    NbsInfo:
      type: object
      nullable: true
      description: >
        Register regulovaných subjektov Národnej banky Slovenska (NBS).
        Dostupné pre plány s funkciou nbs.
      properties:
        is_regulated:
          type: boolean
          description: Či je subjekt regulovaným subjektom finančného trhu
          example: false
        license_types:
          type: array
          items:
            type: string
          example: []
        categories:
          type: array
          items:
            type: string
          example: []

    TaxReliabilityInfo:
      type: object
      nullable: true
      description: >
        Index daňovej spoľahlivosti (Finančná správa SR).
        Dostupné pre plány s funkciou tax_reliability.
      properties:
        index:
          type: string
          nullable: true
          description: Textová hodnota indexu daňovej spoľahlivosti
          example: 'spoľahlivý'
        is_reliable:
          type: boolean
          nullable: true
          description: false ak index = "menej spoľahlivý", null ak subjekt nie je evidovaný
          example: true

    ErasedVatInfo:
      type: object
      nullable: true
      description: >
        Zoznam platiteľov DPH vymazaných zo zoznamu (Finančná správa SR).
        Dostupné pre plány s funkciou erased_vat.
      properties:
        is_erased:
          type: boolean
          description: Či bol subjekt niekedy vymazaný zo zoznamu platiteľov DPH
          example: false
        entries:
          type: array
          items:
            type: object
            properties:
              ic_dph:
                type: string
                example: 'SK2020123456'
              violation_year:
                type: integer
                nullable: true
                example: 2023
              erased_at:
                type: string
                format: date
                nullable: true
                example: '2024-02-15'

    RegesInfo:
      type: object
      nullable: true
      description: >
        Zoznam hospodárskych subjektov ÚVO (UVO REGES). Dostupné pre plány s funkciou uvo_reges.
      properties:
        is_qualified_supplier:
          type: boolean
          description: Či je subjekt aktuálne zapísaný ako kvalifikovaný dodávateľ
          example: true
        registration_id:
          type: string
          nullable: true
          description: Registračné číslo v zozname ÚVO
          example: 'ZHS-2024-0001'
        valid_from:
          type: string
          format: date
          nullable: true
          example: '2023-01-01'
        valid_to:
          type: string
          format: date
          nullable: true
          example: '2025-12-31'

    SocialEnterpriseInfo:
      type: object
      nullable: true
      description: >
        Register sociálnych podnikov (Ministerstvo práce, sociálnych vecí a rodiny SR).
        Dostupné pre plány s funkciou social_enterprise.
      properties:
        is_registered:
          type: boolean
          description: Či je subjekt registrovaný ako sociálny podnik
          example: false
        type:
          type: string
          nullable: true
          description: Typ sociálneho podniku
          example: 'integračný sociálny podnik'
        granted_at:
          type: string
          format: date
          nullable: true
          description: Dátum udelenia certifikátu
          example: '2022-06-15'
        certificate_number:
          type: string
          nullable: true
          description: Číslo certifikátu
          example: 'SP-2022-0042'
        status:
          type: string
          nullable: true
          description: Aktuálny stav registrácie
          example: 'aktívny'

    GleifInfo:
      type: object
      nullable: true
      description: >
        GLEIF – Legal Entity Identifier (LEI). Dostupné pre plány s funkciou gleif.
        Null ak spoločnosť nemá pridelený LEI kód.
      properties:
        lei:
          type: string
          description: LEI kód (20-znakový alfanumerický identifikátor)
          example: '2138005T1LZZ8D1I0Z54'
        parent_lei:
          type: string
          nullable: true
          description: LEI priameho vlastníka (Level 1)
          example: null
        ultimate_parent_lei:
          type: string
          nullable: true
          description: LEI konečného vlastníka (Level 2 ultimate parent)
          example: null
        status:
          type: string
          nullable: true
          description: Status LEI záznamu (ISSUED, LAPSED, MERGED, RETIRED, TRANSFERRED, ANNULLED)
          example: 'ISSUED'
        registration_status:
          type: string
          nullable: true
          description: Stav registrácie v GLEIF (PUBLISHED, PENDING_ARCHIVAL, atd.)
          example: 'PUBLISHED'

    SanctionsInfo:
      type: object
      nullable: true
      description: >
        Sankčné zoznamy – EU Konsolidovaný finančný sankčný zoznam (FSF) a OFAC SDN/Consolidated.
        Dostupné pre plány s funkciou sanctions.
      properties:
        eu_fsf_hits:
          type: array
          description: Zhody v EU FSF zozname
          items:
            type: object
            additionalProperties: true
          example: []
        ofac_hits:
          type: array
          description: Zhody v OFAC zoznamoch (SDN + Consolidated)
          items:
            type: object
            additionalProperties: true
          example: []
        total_hits:
          type: integer
          description: Celkový počet zhôd vo všetkých sankčných zoznamoch
          example: 0

    TedTendersInfo:
      type: object
      nullable: true
      description: >
        TED – Tenders Electronic Daily (európske verejné obstarávania).
        Dostupné pre plány s funkciou ted.
      properties:
        count:
          type: integer
          description: Celkový počet nájdených oznámení ako obstarávateľ
          example: 3
        latest:
          type: array
          description: Posledných 5 oznámení
          items:
            type: object
            properties:
              publication_number:
                type: string
                example: '2024/S 001-000001'
              title:
                type: string
                nullable: true
                example: 'Dodávka IT vybavenia'
              publication_date:
                type: string
                format: date
                nullable: true
                example: '2024-01-15'
              value:
                type: number
                nullable: true
                description: Hodnota zákazky v mene currency
                example: 150000.00
              currency:
                type: string
                nullable: true
                example: 'EUR'
        total_value:
          type: number
          description: Celková hodnota všetkých zákaziek
          example: 450000.00

    ReplikAdministratorInfo:
      type: object
      nullable: true
      description: >
        REPLIK – Zoznam správcov konkurznej podstaty (justice.gov.sk).
        Dostupné pre plány s funkciou insolvency_admins.
        Null ak spoločnosť nie je registrovaná ako správca.
      properties:
        license_number:
          type: string
          description: Číslo licencie správcu
          example: 'S1234'
        region:
          type: string
          nullable: true
          description: Región pôsobenia správcu
          example: 'Bratislava'
        status:
          type: string
          nullable: true
          description: Stav licencie
          example: 'aktívny'
        valid_from:
          type: string
          format: date
          nullable: true
          example: '2020-01-01'
        valid_to:
          type: string
          format: date
          nullable: true
          example: null

    SbsInfo:
      type: object
      nullable: true
      description: >
        MV SR – Register súkromných bezpečnostných služieb (SBS).
        Dostupné pre plány s funkciou sbs_licence.
      properties:
        has_licence:
          type: boolean
          description: Či má subjekt platnú licenciu SBS
          example: false
        license_number:
          type: string
          nullable: true
          description: Číslo licencie
          example: null
        license_type:
          type: string
          nullable: true
          description: Typ licencie SBS
          example: null
        valid_from:
          type: string
          format: date
          nullable: true
          example: null
        valid_to:
          type: string
          format: date
          nullable: true
          example: null

    TransportLicenceInfo:
      type: object
      nullable: true
      description: >
        JISCD – Register dopravcov a odborne spôsobilých osôb v cestnej doprave.
        Dostupné pre plány s funkciou transport_licence.
      properties:
        has_licence:
          type: boolean
          description: Či má subjekt dopravnú licenciu
          example: false
        eurolicence_number:
          type: string
          nullable: true
          description: Číslo eurolicencie
          example: null
        vehicles_count:
          type: integer
          nullable: true
          description: Počet vozidiel
          example: null
        valid_from:
          type: string
          format: date
          nullable: true
          example: null
        valid_to:
          type: string
          format: date
          nullable: true
          example: null

    UtilityLicenceInfo:
      type: object
      nullable: true
      description: >
        ÚRSO – Úrad pre reguláciu sieťových odvetví, držitelia povolení.
        Dostupné pre plány s funkciou utility_licence.
        Jeden subjekt môže mať viacero povolení pre rôzne segmenty.
      properties:
        has_licences:
          type: boolean
          description: Či má subjekt aspoň jedno povolenie ÚRSO
          example: false
        segments:
          type: array
          description: Zoznam povolení podľa segmentu
          items:
            type: object
            properties:
              licence_number:
                type: string
                description: Číslo rozhodnutia/povolenia
                example: '2024E0001'
              segment:
                type: string
                description: Segment siete (electricity, gas, heat, water)
                example: 'electricity'
              valid_from:
                type: string
                format: date
                nullable: true
                example: '2024-01-01'
              valid_to:
                type: string
                format: date
                nullable: true
                example: '2028-12-31'

    ContractingAuthorityInfo:
      type: object
      nullable: true
      description: >
        ÚVO – Register verejných obstarávateľov a obstarávateľov.
        Indicates whether the company is a registered contracting authority
        and lists the statutory section under which it is registered.
        Dostupné pre plány s funkciou contracting_authority.
      properties:
        is_contracting_authority:
          type: boolean
          description: Či je subjekt verejný obstarávateľ
          example: true
        classification_section:
          type: string
          nullable: true
          description: Paragraf zákona o VO podľa ktorého je subjekt klasifikovaný
          example: '§ 7 ods. 1 písm. d)'
        classification_label:
          type: string
          nullable: true
          description: Popis klasifikácie obstarávateľa
          example: 'Právnická osoba financovaná prevažne z verejných zdrojov'

    DebarredInfo:
      type: object
      nullable: true
      description: >
        ÚVO – Register osôb so zákazom účasti vo verejnom obstarávaní.
        Risk signal: indicates whether the company is currently under
        a debarment order and provides the underlying violation reason
        and ban window. Dostupné pre plány s funkciou debarred.
      properties:
        is_debarred:
          type: boolean
          description: Či má subjekt aktuálne aktívny zákaz (banned_until v budúcnosti alebo prázdny)
          example: false
        is_listed:
          type: boolean
          description: Či je subjekt vôbec evidovaný v registri zákazov (vrátane uplynutých)
          example: true
        status:
          type: string
          nullable: true
          description: Stav záznamu v registri ÚVO
          example: 'Vykonateľný'
        violation_reason:
          type: string
          nullable: true
          description: Dôvod porušenia zákona o VO
          example: 'Porušenie § 13 zákona č. 343/2015 Z.z.'
        banned_from:
          type: string
          format: date
          nullable: true
          description: Začiatok zákazu
          example: '2024-06-15'
        banned_until:
          type: string
          format: date
          nullable: true
          description: Koniec zákazu (null = doba neurčitá)
          example: '2027-06-15'

    UvoReferencesInfo:
      type: object
      nullable: true
      description: >
        ÚVO – Evidencia referencií zo splnených verejných zákaziek.
        Aggregate counts plus a preview of the 25 most recent contract
        evaluations. Hodnoty sú v EUR. Dostupné pre plány s funkciou
        uvo_references.
      properties:
        count:
          type: integer
          description: Celkový počet referencií evidovaných pre subjekt
          example: 47
        total_value:
          type: number
          format: float
          description: Súčet hodnoty zmlúv v EUR
          example: 1284900.50
        currency:
          type: string
          example: 'EUR'
        latest:
          type: array
          description: Najnovšie referencie zoradené podľa published_at
          items:
            type: object
            properties:
              buyer_name:
                type: string
                description: Názov obstarávateľa
                example: 'Ministerstvo zdravotníctva SR'
              contract_subject:
                type: string
                description: Predmet zmluvy
                example: 'Dodávka zdravotníckeho materiálu'
              document_url:
                type: string
                nullable: true
                description: URL dokumentu na uvo.gov.sk
                example: 'https://www.uvo.gov.sk/.../detail/123'
              rating:
                type: string
                nullable: true
                description: Hodnotenie referencie
                example: 'A'
              published_at:
                type: string
                format: date
                nullable: true
                example: '2025-09-12'
              value:
                type: number
                format: float
                nullable: true
                description: Hodnota zmluvy v EUR
                example: 20801.00

    CrpProjectsInfo:
      type: object
      nullable: true
      description: >
        CRP – Register projektov. Štátne a EÚ-financované projekty, ktorých je
        subjekt prijímateľom. Agregované počty + náhľad 25 najnovších projektov.
        Hodnoty sú v EUR. Dostupné pre plány s funkciou crp.
      properties:
        count:
          type: integer
          description: Celkový počet projektov evidovaných pre subjekt
          example: 12
        total_value:
          type: number
          format: float
          description: Súčet výšky poskytnutej pomoci v EUR
          example: 3133964.39
        currency:
          type: string
          example: 'EUR'
        latest:
          type: array
          description: Najnovšie projekty zoradené podľa published_at
          items:
            type: object
            properties:
              crp_id:
                type: string
                description: Identifikátor projektu v CRP
                example: '217988'
              name:
                type: string
                description: Názov projektu
                example: 'Bystrany – vodovod, kanalizácia a ČOV'
              provider:
                type: string
                nullable: true
                description: Poskytovateľ pomoci
                example: 'Úrad vlády Slovenskej republiky'
              help_type:
                type: string
                nullable: true
                description: Typ poskytnutej pomoci
                example: 'Nenávratný finančný príspevok'
              amount:
                type: number
                format: float
                nullable: true
                description: Výška pomoci v EUR
                example: 3133964.39
              published_at:
                type: string
                format: date
                nullable: true
                example: '2024-05-12'
              detail_url:
                type: string
                description: URL detailu projektu na crp.gov.sk
                example: 'https://www.crp.gov.sk/bystrany-vodovod-kanalizacia-a-cov-i-a-cast-iii-etapy/'

    FsData:
      type: object
      nullable: true
      description: >
        Daňové údaje z Finančnej správy SR – nadmerné odpočty DPH, zoznamy platiteľov,
        daň z príjmov, R&D odpočty, patentový box a ďalšie. Dostupné pre plány
        s funkciou fs_imports. Aktualizované denne.
      properties:
        dphno:
          type: array
          nullable: true
          description: Zoznam nadmerných odpočtov DPH (§79 zákona o DPH)
          items:
            type: object
            properties:
              period:
                type: string
                description: Zdaňovacie obdobie vo formáte YYYY/MM alebo YYYY/QQ
                example: '2024/12'
              excess_eur:
                type: number
                format: float
                nullable: true
                description: Suma nadmerného odpočtu v EUR
                example: 1234.56
              own_tax_eur:
                type: number
                format: float
                nullable: true
                description: Vlastná daňová povinnosť v EUR
                example: null
        dpho:
          type: array
          nullable: true
          description: Zoznam platiteľov DPH (aktuálne registrácie)
          items:
            type: object
            properties:
              ic_dph:
                type: string
                description: IČ DPH pridelené platiteľovi
                example: 'SK2020123456'
              started_at:
                type: string
                format: date
                nullable: true
                description: Dátum registrácie za platiteľa DPH
                example: '2024-01-15'
              ended_at:
                type: string
                format: date
                nullable: true
                description: Dátum ukončenia registrácie (null = aktívna)
                example: null
        dphz:
          type: array
          nullable: true
          description: Dôvody zrušenia registrácie DPH
          items:
            type: object
            properties:
              year:
                type: integer
                description: Rok zrušenia registrácie
                example: 2023
              published_at:
                type: string
                format: date
                nullable: true
                description: Dátum zverejnenia
                example: '2024-03-01'
        dppos:
          type: array
          nullable: true
          description: Daň z príjmov právnických osôb (DPPO) – prehľad podaných daňových priznaní
          items:
            type: object
            properties:
              period_from:
                type: string
                format: date
                nullable: true
                description: Začiatok zdaňovacieho obdobia
                example: '2024-01-01'
              period_to:
                type: string
                format: date
                nullable: true
                description: Koniec zdaňovacieho obdobia
                example: '2024-12-31'
              tax_eur:
                type: number
                format: float
                nullable: true
                description: Daňová povinnosť v EUR
                example: 48000.00
              loss_eur:
                type: number
                format: float
                nullable: true
                description: Daňová strata v EUR
                example: null
        dsrdp_registered:
          type: boolean
          nullable: true
          description: Príznak registrácie v zozname spoľahlivých platiteľov DPH (DS RDP)
          example: true
        dph_oud:
          type: array
          nullable: true
          description: Osobné účty platiteľov DPH – jeden záznam na IBAN
          items:
            type: object
            properties:
              name:
                type: string
                nullable: true
                description: Názov držiteľa účtu
              iban:
                type: string
                nullable: true
                example: 'SK1211000000001234567890'
              bank_code:
                type: string
                nullable: true
                example: '1100'
              street:
                type: string
                nullable: true
              city:
                type: string
                nullable: true
              postal_code:
                type: string
                nullable: true
              country:
                type: string
                nullable: true
        rd_deduction:
          type: array
          nullable: true
          description: Odpočty výdavkov na výskum a vývoj (R&D odpočty)
          items:
            type: object
            properties:
              period:
                type: string
                nullable: true
                description: Zdaňovacie obdobie
                example: '2023'
              amount_eur:
                type: number
                format: float
                nullable: true
                description: Suma odpočtu v EUR
                example: 25000.00
              project:
                type: string
                nullable: true
                description: Názov alebo popis projektu výskumu a vývoja
                example: 'Vývoj nového softvérového riešenia'
              started_at:
                type: string
                format: date
                nullable: true
                description: Dátum začatia projektu
                example: '2022-01-01'
        investment_deduction:
          type: array
          nullable: true
          description: Investičné stimuly – odpočty z dane pri investičných projektoch
          items:
            type: object
            properties:
              period:
                type: string
                nullable: true
                description: Zdaňovacie obdobie
                example: '2023'
              amount_eur:
                type: number
                format: float
                nullable: true
                description: Suma odpočtu v EUR
                example: 100000.00
              investment_eur:
                type: number
                format: float
                nullable: true
                description: Objem investície v EUR
                example: 500000.00
              percent_planned:
                type: number
                format: float
                nullable: true
                description: Percento plánovaného čerpania stimulu
                example: 20.00
        patent_box:
          type: array
          nullable: true
          description: Patentový box – oslobodenie príjmov z duševného vlastníctva od dane (§13a zákona o dani z príjmov)
          items:
            type: object
            properties:
              subtype:
                type: string
                nullable: true
                description: Podtyp patentového boxu (napr. a6 pre softvér)
                example: 'a6'
              period:
                type: string
                nullable: true
                description: Zdaňovacie obdobie
                example: '2023'
              exemption_eur:
                type: number
                format: float
                nullable: true
                description: Suma oslobodenia v EUR
                example: 15000.00
              patent_text:
                type: string
                nullable: true
                description: Popis predmetu duševného vlastníctva
                example: 'Softvér pre spracovanie dát'
        regulated:
          type: array
          nullable: true
          description: Regulované subjekty sledované Finančnou správou SR
          items:
            type: object
            properties:
              type:
                type: string
                nullable: true
                description: Typ regulovaného subjektu
                example: 'devizový obchodník'
              from:
                type: string
                format: date
                nullable: true
                description: Začiatok regulácie
                example: '2020-01-01'
              to:
                type: string
                format: date
                nullable: true
                description: Koniec regulácie (null = aktívna)
                example: null

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Company not found

    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: Invalid or missing API key

    Forbidden:
      description: Feature not available on your plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: forbidden
            message: This feature requires a Starter plan or higher

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'

    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds until rate limit resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limit_exceeded
            message: Too many requests. Please try again later.
