swagger: '2.0'
info:
  description: Swedish Companies Registration Office API for annual report events
  version: '2.0'
  title: API for electronic annual report events
  contact:
    name: The Swedish Companies Registration Office Group for electronic annual reports
    email: emsdiar@bolagsverket.se
  license:
    name: Public document according to the Swedish Press Act
    url: 'http://www.notisum.se/rnp/sls/lag/19490105.htm#K2P3'
externalDocs:
  description: Information aboud electronic annual reports
  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: Services that retrieve information about annual report events
paths:
  '/handelser':
    post:
      tags:
      - handelser
      summary: Retrieve annual report events for public companies.
      description: >-
        The service delivers events that you already subscribe to and that you need
        to retrieve, e.g. if they have not arrived.
      operationId: handelser
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: anropsobjekt
        description: URL and organisation number
        in: body
        required: true
        schema:
          $ref: '#/definitions/HandelserAnrop'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/HandelserOK'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Fel'
        '403':
          description: Unauthorized user of service
          schema:
            $ref: '#/definitions/Fel'
        '500':
          description: Unspecified technical problem
          schema:
            $ref: '#/definitions/Fel'
        '503':
          description: The service is temporarily unavailable
          schema:
            $ref: '#/definitions/Fel'
        '504':
          description: Timeout
          schema:
            $ref: '#/definitions/Fel'
definitions:
  HandelserAnrop:
    type: object
    description: Request object for the annual report event service
    properties:
      url:
        description: URL for subscription to annual report events.
        type: string
      orgnr:
        type: array
        items:
          description: >-
            Organisation numbers for which events are to be retrieved.
          type: string
          pattern: '[0-9]{10}'
      fromtidpunkt:
        description: Start timestamp for annual report events.
        type: string
        format: date-time
      tomtidpunkt:
        description: End timestamp for annual report events.
        type: string
        format: date-time
    required: ["url"]
  HandelserOK:
    type: object
    description: Response object for the annual report event service.
    properties:
      meddelanden:
        type: array
        items:
          $ref: '#/definitions/Pushmeddelande'
  Pushmeddelande:
    type: object
    description: Push message sent from the Swedish Companies Registration Office
      to those who subscribe to events with type and ID.
    properties:
      typ:
        type: string
        maxLength: 20
        description: Type of event. Always starts with AR for push notifications regarding
          annual reports.
        example: AR-v2
      id:
        type: string
        maxLength: 40
        description: The identity of the event in the form of the organization number
          for the organization.
        example: "5566778899"
      nr:
        type: integer
        format: int64
        description: |
          Sequence number of the event. Gaps in this sequence mean that there are events that have not reached the external party.
          If a test message is sent, these numbers get -1 and can be ignored.
        example: 12
      tid:
        type: string
        format: date-time
        description: Time when the event occurred.
      data:
        $ref: '#/definitions/Arsredovisningshandelse'
    required: ["typ", "id", "nr", "tid", "data"]
  Arsredovisningshandelse:
    type: object
    description: Information on status changes for electronically submitted annual
      reports.
    properties:
      version:
        type: string
        maxLength: 10
        pattern: '[0-9]+\.[0-9]+'
        description: Version for the annual report event.
        example: '2.0'
      handlingsinfo:
        type: array
        description: |
          Contains information about one / several submitted document(s) on a company registration number.
          Test messages (status 'test') have no documents
        items:
          $ref: '#/definitions/Handlingsinfo'
        minItems: 0
      status:
        type: string
        description: Current status of the annual report. Status 'test' does not occur
          when events are fetched 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: >-
          Specifies the type of document, eg arsredovisning (annual report). There
          is always an annual report (main document) included in the list. If the
          audit report is submitted separately, it is also included in the list. If
          the annual report is submitted together with a certificate (different certificates
          depending on the type of organization), then one of the certificate types
          is included in the list.
        enum:
        - arsredovisning
        - revisionsberattelse
        - faststallelseintyg
        - bestyrkandeintyg
      idnummer:
        type: string
        maxLength: 36
        description: Unique identification number for the document submitted.
        example: '30acf69f-26b4-4192-8bf1-c470bb79e9ee'
      kontrollsumma:
        $ref: '#/definitions/Kontrollsumma'
    required: ["handling", "idnummer"]
  Kontrollsumma:
    type: object
    description: Contains the checksum, algorithm and possible information in case
      an error has occurred for a specific document.
    properties:
      digest:
        type: string
        format: byte
        description: The checksum contained in the file.
        maxLength: 100
        example: WhiJ4NAOkpwco83BSrAIuTjGvEIwRlDbPtoTO31J8HA=
      algoritm:
        type: string
        description: Algorithm used to generate checksum.
        example: SHA-256
      upplysning:
        type: string
        description: An information is displayed when the checksum in the file does
          not match the contents of the file.
        example: Kontrollsumman stämmer inte
    required: ["digest", "algoritm"]
  Upplysning:
    type: object
    description: Contains further details on errors etc.
    properties:
      kod:
        type: integer
        format: int32
        description: Code that describes the kind of information. Described in a separate
          document.
      text:
        type: string
        description: Text that leaves further information.
      typ:
        type: string
        description: Classification of the information - info, warning or error.
        enum:
        - info
        - warn
        - error
    required: ["kod", "text", "typ"]
  Fel:
    type: object
    description: Provides detailed error information.
    properties:
      kod:
        type: integer
        format: int32
        description: Code that describes the error. Described in a separate document.
      text:
        type: string
        description: Text that leaves further information about the error.
      detaljinformation:
        type: array
        description: Detailed information about the error
        items:
          $ref: '#/definitions/Upplysning'
    required: ["kod", "text"]