swagger: '2.0'
info:
  description: Swedish Companies Registration Office API for electronic annual reports
  version: '1.3'
  title: API for electronic annual reports
  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'}
host: api.bolagsverket.se
basePath: /lamna-in-arsredovisning/v1.3
schemes: [https]
tags:
- {name: inlamning, description: Services that receive electronic annual reports for signing}
- {name: kontroll, description: Services complementing submission of electronic annual reports}
paths:
  /skapa-inlamningtoken:
    post:
      tags: [inlamning]
      summary: Create token for verification and submission to separate space
      description: The service creates the token for use when verifying and submitting an annual report. The same token is used both as kontrolltoken in operation /kontrollera/{kontrolltoken} and as inlamningtoken in operation /inlamning/{inlamningtoken}.
      operationId: skapa-inlamningtoken
      consumes: [application/json;charset=utf-8]
      produces: [application/json;charset=utf-8]
      parameters:
      - name: anropsobjekt
        description: Personal identification number and organization number
        in: body
        required: true
        schema: {$ref: '#/definitions/SkapaInlamningTokenAnrop'}
      responses:
        '200':
          description: Tasks received
          schema: {$ref: '#/definitions/SkapaTokenOK'}
        '400':
          description: Bad request
          schema: {$ref: '#/definitions/Fel'}
        '403':
          description: Unauthorized user of service
          schema: {$ref: '#/definitions/Fel'}
        '404':
          description: Personal identification number is missing
          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'}
  /inlamning/{inlamningtoken}:
    post:
      tags: [inlamning]
      summary: Submit an annual report to the separate space belonging to the user for review and electronic signing
      description: "The service checks that the electronic annual report is well-formed\
        \ and stores it in the separate space belonging to the user.\nIf the document\
        \ passes inspection and the flag mobiltbankid is false, no further action\
        \ is needed from the client (the annual report should be signed later using\
        \ the web page).    \nIf the document passes inspection and the flag mobiltbankid\
        \ is set to true, a transaction for direct electronic signing is created and\
        \ the annual report is received after signing has completed. Please note that\
        \ in this case the API call returns a code 202 immediately (before the annual\
        \ report has been signed). The calling software should poll the /inlamning-status\
        \ operation to ensure that signing is successful."
      operationId: inlamning
      consumes: [application/json;charset=utf-8]
      produces: [application/json;charset=utf-8]
      parameters:
      - {name: inlamningtoken, in: path, description: Token for submission, required: true,
        type: string, format: uuid}
      - name: anropsobjekt
        description: Other information and the annual report
        in: body
        required: true
        schema: {$ref: '#/definitions/InlamningAnrop'}
      responses:
        '200':
          description: Annual report is submitted to separate space for later signature via web.
          schema: {$ref: '#/definitions/InlamningOK'}
        '202':
          description: |-
            The annual report has been submitted to a separate space and a signing transaction has been created.
            The software should call /inlamning-status to ensure that signing is successful and that the annual report has been received.
          schema: {$ref: '#/definitions/InlamningOK'}
        '400':
          description: Bad request
          schema: {$ref: '#/definitions/Fel'}
        '403':
          description: Unauthorized user of service
          schema: {$ref: '#/definitions/Fel'}
        '404':
          description: Organisation number missing
          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'}
  /inlamning-status/{underskrifttoken}:
    get:
      tags: [inlamning]
      summary: Retrieve the current submission status after submission with direct signing
      description: |-
        The service returns actual processing status for an annual report that has been marked for direct signing.
        Poll this service repeatedly while it returns status code underskrift_pagaende (wait for a few seconds between calls to avoid overload) .
        When status code arsredovisning_mottagen is returned, the annual report has been received. In this case the response will contain a receipt number and a timestamp.
      operationId: inlamning-status
      consumes: [application/json;charset=utf-8]
      produces: [application/json;charset=utf-8]
      parameters:
      - {name: underskrifttoken, in: path, description: Signature token from submission to separate space,
        required: true, type: string, format: uuid}
      responses:
        '200':
          description: Current submission status
          schema: {$ref: '#/definitions/Inlamningstatus'}
        '400':
          description: Bad request
          schema: {$ref: '#/definitions/Fel'}
        '403':
          description: Unauthorized user of service
          schema: {$ref: '#/definitions/Fel'}
        '404':
          description: Missing signature token
          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'}
  /kontrollera/{kontrolltoken}:
    post:
      tags: [kontroll]
      summary: Verify annual report before submission to separate space
      operationId: kontrollera
      consumes: [application/json;charset=utf-8]
      produces: [application/json;charset=utf-8]
      parameters:
      - {name: kontrolltoken, in: path, description: Token for verification, required: true,
        type: string, format: uuid}
      - name: anropsobjekt
        description: The annual report
        in: body
        required: true
        schema: {$ref: '#/definitions/KontrolleraAnrop'}
      responses:
        '200':
          description: The annual report is verified, see outcome. The user of the client software should be informed about the outcome. The annual report can be submitted to the separate space regardless of outcome.
          schema: {$ref: '#/definitions/KontrolleraSvar'}
        '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'}
parameters:
  orgnrPathParam: {name: orgnr, in: path, required: true, type: string, pattern: '[0-9]{10}',
    description: 'Organisation number for the public company. Ten digits, no dash.'}
definitions:
  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]
  SkapaTokenOK:
    type: object
    properties:
      token: {type: string, format: uuid, description: Token for verification och inlämning}
      avtalstext: {type: string, description: Text to show to the end user.}
      avtalstextAndrad: {type: string, format: date, description: Date of last change of agreement text.}
    required: [token]
  InlamningOK:
    type: object
    properties:
      orgnr: {type: string, pattern: '[0-9]{10}', description: 'Organisation number
          for the public company. Ten digits, no dash.'}
      avsandare: {description: Personal identification number incl. century of person to whom the document is stored,
        type: string, pattern: '(19|20)[0-9]{10}'}
      undertecknare: {description: Personal ID number of the signer including century,
        type: string, pattern: '(19|20)[0-9]{10}'}
      dokumentlangd: {type: integer, format: int32, description: The length in bytes of the submitted document}
      idnummer: {type: string, description: ID number of the document in the separate space belonging to the user. For debugging use only.}
      url: {type: string, description: Url where the annual report is signed.}
      sha256checksumma: {type: string, format: byte, description: SHA-256 checksum of the submitted document}
      underskrifttoken: {type: string, format: uuid, description: Signature to use to check the status of an initiated direct signing via call to /inlamning with mobiltbankid set true.}
    required: [orgnr, avsandare, undertecknare, dokumentlangd, idnummer, url, sha256checksumma]
  SkapaInlamningTokenAnrop:
    type: object
    description: Query object for personal identification number and organization number
    properties:
      pnr: {description: Personal identification number incl. century of person to whom the document is to be stored.,
        type: string, pattern: '(19|20)[0-9]{10}'}
      orgnr: {type: string, pattern: '[0-9]{10}', description: 'Organisation number
          for the public company. Ten digits, no dash.'}
    required: [pnr, orgnr]
  InlamningAnrop:
    type: object
    description: Call object for submission of annual report to separate space
    properties:
      undertecknare: {description: Personal ID number of the signer including century,
        type: string, pattern: '(19|20)[0-9]{10}'}
      mobiltbankid: {type: boolean, description: Flag that controls whether the signing should be started directly with mobilt bankid. Default is false}
      epostadresser:
        description: |-
          If parameter mobiltbankid is false, email recipients will be notified that there is an annual report to sign.
          If parameter mobiltbankid is true, email recipients will be sent a receipt of the annual report.
        type: array
        items: {type: string, minLength: 6, maxLength: 250}
      arsredovisningsfil: {type: string, format: byte, description: Annual report in iXBRL format. The file shall be encoded in UTF-8.}
    required: [undertecknare, arsredovisningsfil]
  Inlamningstatus:
    type: object
    description: Current status for submission via direct signing
    properties:
      typ:
        type: string
        description: Current status of submission.
        enum: [underskrift_pagaende, underskrift_avbruten, underskrift_timeout, tekniskt_fel,
          arsredovisning_mottagen]
      kvittens: {$ref: '#/definitions/Kvittens'}
    required: [typ]
  Kvittens:
    type: object
    description: Details of the acknowledgment of the direct signed and received annual report
    properties:
      kvittensnummer: {type: string, description: Acknowledgment number for the received annual report}
      tidpunkt: {type: string, format: date-time, description: Time when the annual report was received}
    required: [kvittensnummer, ankomsttidpunkt]
  KontrolleraAnrop:
    type: object
    description: Call object for verification of annual report before submission to separate space
    properties:
      arsredovisningsfil: {type: string, format: byte, description: Annual report in iXBRL format. The file shall be encoded in UTF-8.}
    required: [arsredovisningsfil]
  KontrolleraSvar:
    type: object
    description: Result of verified annual report
    properties:
      orgnr: {type: string, pattern: '[0-9]{10}', description: 'Organisation number
          for the public company. Ten digits, no dash.'}
      utfall:
        type: array
        description: List of outcomes from verification
        items: {$ref: '#/definitions/KontrolleraUtfall'}
  KontrolleraUtfall:
    type: object
    description: Outcome from verification.
    properties:
      kod: {type: string, description: Code corresponding to outcome. Described in a separate document.}
      text: {type: string, description: Text explaining the outcome.}
      typ:
        type: string
        description: Classification of the outcome - info, warning or error.
        enum: [info, warn, error]
      tekniskinformation:
        type: array
        description: Technical information about the outcome, only for logging and troubleshooting.
        items: {$ref: '#/definitions/KontrolleraUtfallTekniskInformation'}
    required: [kod, text, typ]
  KontrolleraUtfallTekniskInformation:
    type: object
    description: Technical information about the outcome.
    properties:
      meddelande: {type: string, description: Technical message}
      element: {type: string}
      varde: {type: string}
externalDocs: {description: Information about electronic annual reports, url: 'http://bolagsverket.se/om/oss/utveckling-av-digitala-tjanster/digital-ingivning'}