#
# Ändringar från v1.3
# - Tagit bort fält 'idnummer' och 'idnummerRevisionsberattelse' i 'data'. Dessa markerades 'deprecated' i v1.3
# - Utökat enum 'handling' med en till variant
# - Utökad längd på fälten 'idnummer' och 'digest'
#

swagger: '2.0'
info:
  description: Bolagsverkets API för att hämta årsredovisningshändelser
  version: '2.0'
  title: API för att hämta årsredovisningshändelser
  contact:
    name: Bolagsverkets grupp för digitala årsredovisningar
    email: emsdiar@bolagsverket.se
  license:
    name: Offentlig handling enligt Tryckfrihetsförordningen 2 Kap 3 §
    url: 'http://www.notisum.se/rnp/sls/lag/19490105.htm#K2P3'
    
externalDocs:
  description: Information om digitala årsredovisningar
  url: 'http://bolagsverket.se/om/oss/utveckling-av-digitala-tjanster/digital-ingivning'

host: api.bolagsverket.se
basePath: /hamta-arsredovisningshandelser/v2.0
schemes:
  - https
tags:
  - name: handelser
    description: Tjänster för att hämta årsredovisningshändelser
paths:
  '/handelser':
    post:
      tags:
        - handelser
      summary: Hämta årsredovisningshändelser för aktiebolag.
      description: >-
        Tjänsten levererar händelser som man redan prenumererar på och som man behöver hämta på nytt, t.ex. om de inte nått fram.
      operationId: handelser
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: anropsobjekt
          description: URL och organisationsnummer
          in: body
          required: true
          schema:
            $ref: '#/definitions/HandelserAnrop'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/HandelserOK'
        '400':
          description: Felaktig request
          schema:
            $ref: '#/definitions/Fel'
        '403':
          description: Obehörig användare av tjänsten
          schema:
            $ref: '#/definitions/Fel'
        '500':
          description: Ospecificerat tekniskt fel
          schema:
            $ref: '#/definitions/Fel'
        '503':
          description: Tjänsten temporärt otillgänglig
          schema:
            $ref: '#/definitions/Fel'
        '504':
          description: Timeout
          schema:
            $ref: '#/definitions/Fel'

definitions:
  HandelserAnrop:
    type: object
    description: Anropsobjekt för att hämta tidigare årsredovisningshändelser
    properties:
      url:
        description: URL för årsredovisningshändelser.
        type: string
      orgnr: 
        type: array
        items: 
          description: >-
            De organisationsnummer som man vill hämta händelser för.
          type: string
          pattern: '[0-9]{10}'
      fromtidpunkt:
        description: Tidpunkt fr.o.m. då man vill hämta årsredovisningshändelser.
        type: string
        format: date-time
      tomtidpunkt:
        description: Tidpunkt t.o.m. då man vill hämta årsredovisningshändelser.
        type: string
        format: date-time
    required: ["url"]
  HandelserOK:
    type: object
    description: Svar på fråga om årsredovisningshändelser.
    properties:
      meddelanden:
        type: array
        items: 
          $ref: '#/definitions/Pushmeddelande'

  Pushmeddelande:
    type: object
    description: Pushmeddelande som skickas från Bolagsverket till de som prenumererar på händelser med typ och id.
    properties:
      typ:
        type: string
        maxLength: 20
        description: Typ av händelse. Börjar alltid på AR för pushmeddelanden gällande årsredovisningar.
        example: AR-v2
      id:
        type: string
        maxLength: 40
        description: Händelsens identitet i form av organisationsnumret för organisationen.
        example: "5566778899"
      nr:
        type: integer
        format: int64
        description: |
          Händelsens ordningsnummer. Luckor i denna sekvens betyder att det finns händelser som inte nått fram till den externa parten.
          Om testmeddelande skickas ut får dessa nummer -1 och kan ignoreras.
        example: 12
      tid:
        type: string
        format: date-time
        description: Tidpunkt då händelsen inträffade.
      data: 
        $ref: '#/definitions/Arsredovisningshandelse'
    required: ["typ", "id", "nr", "tid", "data"]

  Arsredovisningshandelse:
    type: object
    description: Information om statusförändringar för elektroniskt inkomna årsredovisningar.
    properties:
      version:
        type: string
        maxLength: 10
        pattern: '[0-9]+\.[0-9]+'
        description: Version för årsredovisningshändelsen.
        example: '2.0'
      handlingsinfo:
        type: array
        description: |
          Innehåller information om en / flera inlämnade handling(ar) på ett orgnr.
          Testmeddelanden (status: 'test') har dock inga handlingar.
        items:
          $ref: '#/definitions/Handlingsinfo'
        minItems: 0
      status:
        type: string
        description: Aktuell status för årsredovisningen. Status 'test' förekommer inte när meddelanden hämtas via API.
        enum:
          - arsred_inkommen
          - arsred_registrerad
          - arsred_avslutad_ej_registrerad
          - arsred_forelaggande_skickat
          - arsred_komplettering_inkommen
          - test
    required: ["version", "status", "handlingsinfo"]
  
  Handlingsinfo:
    type: object
    properties:
      handling:
        type: string
        description: >- 
          Specifierar typen på handlingen, t.ex arsredovisning.
          Det finns alltid en årsredovisning (huvudhandling) med i listan.
          Om revisionsberättelse lämnas in separat finns även den i listan.
          Om årsredovisningen lämnas in tillsammans med ett intyg (olika intyg beroende på företagsform) så finns en av intygstyperna med i listan.
        enum:
          - arsredovisning
          - revisionsberattelse
          - faststallelseintyg
          - bestyrkandeintyg
      idnummer:
        type: string
        maxLength: 36
        description: Unikt identifieringsnummer för dokumentet som lämnades in.
        example: '30acf69f-26b4-4192-8bf1-c470bb79e9ee'
      kontrollsumma:
        $ref: '#/definitions/Kontrollsumma'
    required: ["handling", "idnummer"]
  
  Kontrollsumma:
    type: object
    description: Innehåller kontrollsumman, algoritm och eventuell upplysning ifall ett fel har uppstått för specifik handling.
    properties:
      digest:
        type: string
        format: byte
        description: Kontrollsumman som finns i filen.
        maxLength: 100
        example: WhiJ4NAOkpwco83BSrAIuTjGvEIwRlDbPtoTO31J8HA=
      algoritm:
        type: string
        description: Algoritm använd för att generera kontrollsumma.
        example: SHA-256
      upplysning:
        type: string
        description: En upplysning visas när kontrollsumman i filen inte stämmer överens med innehållet i filen.
        example: Kontrollsumman stämmer inte
    required: ["digest", "algoritm"]

  Upplysning:
    type: object
    description: Innehåller mer detaljerad information om ett fel el dyl.
    properties:
      kod:
        type: integer
        format: int32
        description: Kod som beskriver upplysningen. Beskrivs i separat dokument.
      text:
        type: string
        description: Förklarande text till upplysningen.
      typ:
        type: string
        description: Upplysningens karaktär - information, varning eller fel.
        enum:
          - info
          - warn
          - error
    required: ["kod", "text", "typ"]
  Fel:
    type: object
    description: Beskriver fel.
    properties:
      kod:
        type: integer
        format: int32
        description: Kod som beskriver felet. Beskrivs i separat dokument.
      text:
        type: string
        description: Förklarande text till felet.
      detaljinformation:
        type: array
        description: Detaljupplysningar om felet
        items:
          $ref: '#/definitions/Upplysning'
    required: ["kod", "text"]