---
openapi: 3.0.1
info:
  title: Opendata XBRL Api
  version: 2.0
  license:
    name: Creative Commons Nimeä 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers: 
  - url: https://avoindata.prh.fi/opendata-xbrl-api/v3
paths:
  /financials:
    get:
      summary: "Use a Finnish Business ID to search for financial periods of which the service provides digital financial statement information"
      operationId: GetFinancials
      parameters:
        - in: query
          name: businessId
          required: true
          description: "Business ID"
          schema:
            type: string
        - in: query
          name: page
          description: "If your search returns more than 100 results, they are shown on multiple pages. Use the page parameter to indicate the results page you need. If the page parameter is not used, the results of the first page are returned. If the page parameter points to a page not included in the results (for instance if you search for page 5 and the results only have 3 pages), an empty response is returned."
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialResult'
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /all_financials:
    get:
      summary: "Use the end date of the financial period to search for companies that have filed digital financial statements"
      operationId: GetAllFinancials
      parameters:
        - in: query
          name: financialDate
          description: "End date of the financial period in the format yyyy-mm-dd"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: page
          description: "If your search returns more than 100 results, they are shown on multiple pages. Use the page parameter to indicate the results page you need. If the page parameter is not used, the results of the first page are returned. If the page parameter points to a page not included in the results (for instance if you search for page 5 and the results only have 3 pages), an empty response is returned."
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialResult'
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /all_financial_statements:
    get:
      summary: "Use registration dates over a period of time to search for companies that have filed digital financial statements"
      operationId: GetAllFinancialStatements
      parameters:
        - in: query
          name: registeredDateStart
          description: "Registration date of financial statements over a period of time (from 1 July 2023, write the start date in the format yyyy-mm-dd)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: registeredDateEnd
          description: "Registration date of financial statements over a period of time (end date in the format yyyy-mm-dd)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: page
          description: "If your search returns more than 100 results, they are shown on multiple pages. Use the page parameter to indicate the results page you need. If the page parameter is not used, the results of the first page are returned. If the page parameter points to a page not included in the results (for instance if you search for page 5 and the results only have 3 pages), an empty response is returned."
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialResult'
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /financial:
    get:
      summary: "Use a Finnish Business ID and the end date of the financial period to search for digital financial statement information"
      operationId: GetFinancial
      parameters:
        - in: query
          name: businessId
          required: true
          description: "Business ID"
          schema:
            type: string
        - in: query
          name: financialDate
          required: true
          description: "End date of the financial period in the format yyyy-mm-dd"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
      responses:
        200:
          description: "OK"
          content:
            text/xml:
              schema:
                type: string
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Too many requests"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Internal server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "The server cannot process the request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    FinancialResult:
      type: object
      description: "Tilikausien tiedot"
      required: ["totalResults", "financials"]
      properties:
        totalResults:
          type: integer
          format: int64
          description: "Total number of results"
        financials:
          type: array
          description: "Yrityksen tilikausien tiedot"
          items:
            $ref: '#/components/schemas/Financial'
    AllFinancialResult:
      type: object
      description: "Yritysten tilikausien tiedot"
      required: [ "totalResults", "financials" ]
      properties:
        totalResults:
          type: integer
          format: int64
          description: "Total number of results"
        financials:
          type: array
          description: "Yritysten tilikausien tiedot"
          items:
            $ref: '#/components/schemas/Financial'
    Financial:
      type: object
      required: ["businessId", "financialDate"]
      description: "Yrityksen tilikauden tiedot"
      properties:
        businessId:
          type: string
          description: "Business ID, for example 0116297-6"
        financialDate:
          type: string
          format: date
          description: "Tilikauden päivämäärä muodossa YYYY-MM-DD"
          minLength: 10
          maxLength: 10
        registrationDate:
          type: string
          format: date
          description: "Rekisteröinti päivämäärä muodossa vvvv-kk-pp"
          minLength: 10
          maxLength: 10
    ErrorResponse:
      type: object
      required: [ "timestamp", "code" ]
      description: "Error message"
      properties:
        timestamp:
          type: string
          minLength: 19
          maxLength: 19
          format: date-time
          x-field-extra-annotation: "@com.fasterxml.jackson.annotation.JsonFormat(shape = com.fasterxml.jackson.annotation.JsonFormat.Shape.STRING, pattern = \"yyyy-MM-dd HH:mm:ss\")"
          description: "Time, including seconds, without a time zone in the format ‘YYYY-MM-DD 00:00:00'"
        message:
          type: string
          description: "Error message"
          maxLength: 1000
        errorcode:
          type: integer
          format: int32
          description: "Error code"

externalDocs:
  description: "Read more about the taxonomy you need to be able to use the details and about the range of software."
  url: https://avoindata.prh.fi/en/info/swagger-ui