---
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: "Hae Y-tunnuksella tilikaudet, joista palvelussa on digitaalista tilinpäätöstietoa"
      operationId: GetFinancials
      parameters:
        - in: query
          name: businessId
          required: true
          description: "Y-tunnus"
          schema:
            type: string
        - in: query
          name: page
          description: "Jos haku palauttaa yli 100 tulosta, tulokset palautetaan sivutettuina. Page-parametrilla voit kertoa haluamasi tulossivun. Jos page-parametria ei ole annettu, palautetaan ensimmäisen sivun tulokset. Jos page-parametri osoittaa sivulle, jota tuloksista ei löydy (esimerkiksi jos haet sivua 5 ja tuloksissa on vain 3 sivua), palautetaan tyhjä vastaus."
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialResult'
        400:
          description: "Virheellinen pyyntö"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Liian monta pyyntöä"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Sisäinen palvelinvirhe"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "Palvelin ei voi käsitellä pyyntöä"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /all_financials:
    get:
      summary: "Hae tilikauden päättymispäivällä digitaalisia tilinpäätöksiä ilmoittaneita yrityksiä"
      operationId: GetAllFinancials
      parameters:
        - in: query
          name: financialDate
          description: "Tilikauden päättymispäivä muodossa vvvv-kk-pp"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: page
          description: "Jos haku palauttaa yli 100 tulosta, tulokset palautetaan sivutettuina. Page-parametrilla voit kertoa haluamasi tulossivun. Jos page-parametria ei ole annettu, palautetaan ensimmäisen sivun tulokset. Jos page-parametri osoittaa sivulle, jota tuloksista ei löydy (esimerkiksi jos haet sivua 5 ja tuloksissa on vain 3 sivua), palautetaan tyhjä vastaus."
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialResult'
        400:
          description: "Virheellinen pyyntö"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Liian monta pyyntöä"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Sisäinen palvelinvirhe"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "Palvelin ei voi käsitellä pyyntöä"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /all_financial_statements:
    get:
      summary: "Hae rekisteröintipäivien aikavälillä digitaalisen tilinpäätöksen ilmoittaneet yritykset"
      operationId: GetAllFinancialStatements
      parameters:
        - in: query
          name: registeredDateStart
          description: "Tilinpäätöksen rekisteröintipäivä aikavälinä (1.7.2023 alkaen, kirjoita alkamispäivä muodossa vvvv-kk-pp)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: registeredDateEnd
          description: "Tilinpäätöksen rekisteröintipäivä aikavälinä (päättymispäivä muodossa vvvv-kk-pp)"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
        - in: query
          name: page
          description: "Jos haku palauttaa yli 100 tulosta, tulokset palautetaan sivutettuina. Page-parametrilla voit kertoa haluamasi tulossivun. Jos page-parametria ei ole annettu, palautetaan ensimmäisen sivun tulokset. Jos page-parametri osoittaa sivulle, jota tuloksista ei löydy (esimerkiksi jos haet sivua 5 ja tuloksissa on vain 3 sivua), palautetaan tyhjä vastaus."
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialResult'
        400:
          description: "Virheellinen pyyntö"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Liian monta pyyntöä"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Sisäinen palvelinvirhe"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "Palvelin ei voi käsitellä pyyntöä"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /financial:
    get:
      summary: "Hae Y-tunnuksella ja tilikauden päättymispäivällä digitaalista tilinpäätöstietoa"
      operationId: GetFinancial
      parameters:
        - in: query
          name: businessId
          required: true
          description: "Y-tunnus"
          schema:
            type: string
        - in: query
          name: financialDate
          required: true
          description: "Tilikauden päättymispäivä muodossa vvvv-kk-pp"
          schema:
            type: string
            format: date
            minLength: 10
            maxLength: 10
      responses:
        200:
          description: "OK"
          content:
            text/xml:
              schema:
                type: string
        400:
          description: "Virheellinen pyyntö"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        429:
          description: "Liian monta pyyntöä"
          content:
            text/plain:
              schema:
                type: string
        500:
          description: "Sisäinen palvelinvirhe"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: "Palvelin ei voi käsitellä pyyntöä"
          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: "Kokonaistulosten määrä"
        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: "Kokonaistulosten määrä"
        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: "Y-tunnus, esim 0116297-6"
        financialDate:
          type: string
          format: date
          description: "Tilikauden päättymispäivä muodossa vvvv-kk-pp"
          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: "Virheilmoitus"
      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: "Aika sekuntitasolla ilman aikavyöhykettä muodossa 'vvvv-kk-pp 00:00:00'"
        message:
          type: string
          description: "Virheviesti"
          maxLength: 1000
        errorcode:
          type: integer
          format: int32
          description: "Virheen koodi"

externalDocs:
  description: "Lue lisää tietojen käyttöön tarvittavasta taksonomiasta ja ohjelmistotarjonnasta."
  url: https://avoindata.prh.fi/fi/info/swagger-ui