# API-specifikationsmall för programvaruleverantörer att använda för att ta emot pushmeddelanden gällande
# statusförändringar på elektroniskt inlämnade årsredovisningar.
#
# Val av faktisk host, basePath och path görs av programvaruleverantören.
#
# Ändringar från v1.3
# - Tagit bort http som godkänt protokoll (nu accepteras endast https)
# - 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 pushmeddelanden gällande statusförändringar på elektroniskt inlämnade årsredovisningar. 
  version: '2.0'
  title: API för pushmeddelanden gällande årsredovisningar
# Faktisk host bestäms av den externa parten.
host: programvaruleverantor.example.com
# Faktisk basePath bestäms av den externa parten.
basePath: /bolagsverket/
schemes:
  - https
paths:
  # Faktisk path bestäms av den externa parten.
  '/pushmeddelande':
    post:
      summary: Ta emot årsredovisningshändelser från Bolagsverket. 
      operationId: pushmeddelande
      consumes:
        - "application/json"
      parameters:
        - name: Auth
          in: header
          type: string
          required: false
          description: Innehåller den authKey som angavs in då prenumerationen skapades.

        - name: pushmeddelande
          in: body
          required: true
          schema:
            $ref: '#/definitions/Pushmeddelande'
      responses:
        '200':
          description: OK
        '201':
          description: OK
        '202':
          description: OK
        '204':
          description: OK
        default:
          description: Övriga statusar kommer räknas som fel. Bolagsverket kommer då försöka skicka samma meddelande igen.

definitions:

  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"]