swagger: '2.0'
info:
  description: Bolagsverkets API för att hämta årsredovisningshändelser
  version: '1.0'
  title: API för att hämta årsredovisningshändelser
  termsOfService: 'http://diar.bolagsverket.se/api/terms/'
  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'
host: api.bolagsverket.se
basePath: /hamta-arsredovisningshandelser/v1.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 om händelser som rör årsredovisningar för aktiebolag.
      operationId: handelser
      consumes:
        - "application/json;charset=utf-8"
      produces:
        - "application/json;charset=utf-8"
      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:
  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"]
  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/Handelse'
  Handelse:
    type: object
    description: En årsredovisningshändelse.
    properties:
      typ:
        type: string
        maxLength: 20
        description: Typ av händelse.
      id:
        type: string
        maxLength: 40
        description: Händelsens identitet i form av organisationsnumret för aktiebolaget.
      nr:
        type: integer
        format: int64
        description: Händelsens ordningsnummer.
      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:
      status:
        type: string
        description: Aktuell status för årsredovisningen.
        enum:
          - arsred_inkommen
          - arsred_registrerad
          - arsred_avslutad_ej_registrerad

externalDocs:
  description: Information om digitala årsredovisningar
  url: 'http://diar.bolagsverket.se'