openapi: 3.0.3
info:
  title: "Filtransport v3 API"
  description: "Beskrivning av Filtransport v3:s API:er. Observera att ett certifikat utfärdat från Expisoft krävs för att ansluta, läs mer om certifikat [här](https://www.statenspersonadressregister.se/master/start/teknisk-info/program-till-program/organisationscertifikat/)."
  contact:
    name: "Skatteverket"
    url: "https://www.statenspersonadressregister.se"
  version: 1.0.0

externalDocs:
  description: "Information om Filtransport"
  url: "https://www.statenspersonadressregister.se/master/start/teknisk-info/program-till-program/filtransport/"

servers:
  - url: "https://ext-filer.statenspersonadressregister.se/v3"
    description: "Produktionsmiljö"
  - url: "https://kt-ext-filer.statenspersonadressregister.se/v3"
    description: "Kundtestmiljö"

paths:

  /utfil:
    get:
      tags:
        - utfil
      summary: "Lista utfiler"
      description: "Kan anropas med eller utan filtrering på filstatus"
      operationId: "listaUtfiler"
      parameters:
        - in: query
          name: filstatus
          description: "Filstatus att filtrera på"
          required: false
          schema:
            type: string
            enum: [ "ALLA", "NY", "HAMTAD" ]
            default: "ALLA"
            example: "NY"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  utfiler:
                    type: array
                    items:
                      $ref: "#/components/schemas/utfil"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"

  /utfil/{filnamn}:
    get:
      tags:
        - utfil
      summary: "Visa information om angiven utfil"
      operationId: "visaInformationUtfil"
      parameters:
        - in: path
          name: filnamn
          description: "Namn på filen"
          required: true
          schema:
            type: string
            example: "SPARAvisering_20220131123456_SPAR50001-12345.xml.zip"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  utfil:
                    $ref: "#/components/schemas/utfil"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"

  /utfil/hamta/{filnamn}:
    get:
      tags:
        - utfil
      summary: "Hämta angiven utfil"
      operationId: "hamtaUtfil"
      parameters:
        - in: path
          name: filnamn
          description: "Namn på filen"
          required: true
          schema:
            type: string
            example: "SPARAvisering_20220131123456_SPAR50001-12345.xml.zip"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/octet-stream":
              schema:
                description: "En komprimerad XML-fil"
                type: string
                format: binary
        default:
          $ref: "#/components/responses/misslyckadOperation"


  /infil:
    get:
      tags:
        - infil
      summary: "Lista infiler"
      description: "Kan anropas med eller utan filtrering på filstatus"
      operationId: "listaInfiler"
      parameters:
        - name: filstatus
          in: query
          description: "Status att filtrera på"
          required: false
          schema:
            type: string
            enum: [ "ALLA", "MOTTAGEN", "VALIDERAD", "INKORREKT" ]
            default: "ALLA"
            example: "VALIDERAD"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  infiler:
                    type: array
                    items:
                      $ref: "#/components/schemas/infilILista"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"

  /infil/{filnamn}:
    get:
      tags:
        - infil
      summary: "Visa information om angiven infil"
      operationId: "visaInformationInfil"
      parameters:
        - in: path
          name: filnamn
          description: "Namn på filen"
          required: true
          schema:
            type: string
            example: "Uppdrag_12345_2021-01-31T12.00.00_ABcDefGhI+JklMnOpqr1St.xml"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  infil:
                    $ref: "#/components/schemas/infilEnskild"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"

  /infil/avvikelse/{filnamn}:
    get:
      tags:
        - infil
      summary: "Visa avvikelser i angiven infil"
      operationId: "visaAvvikelserInfil"
      parameters:
        - in: path
          name: filnamn
          description: "Namn på filen"
          required: true
          schema:
            type: string
            example: "Uppdrag_12345_2021-01-31T12.00.00_ABcDefGhI+JklMnOpqr1St.xml"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  avvikelser:
                    $ref: "#/components/schemas/avvikelseSamling"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"

  /infil/lamna/{slutkund-kundnummer}/{uppdrag-id}:
    post:
      tags:
        - infil
      summary: "Lämna infil för ett uppdrag"
      operationId: "lamnaFil"
      parameters:
        - in: path
          name: slutkund-kundnummer
          description: "Kundnummer för den slutkund filen lämnas för"
          required: true
          schema:
            type: string
            example: "500001"
        - in: path
          name: uppdrag-id
          description: "Det uppdragsid filen ska lämnas för"
          required: true
          schema:
            type: string
            example: "12345"
      requestBody:
        content:
          "multipart/form-data":
            schema:
              description: "Infil för uppdraget på formatet XML eller CSV, innehåll beror på typ av uppdrag och schemaversion"
              type: object
              properties:
                file:
                 type: string
                 format: binary
      responses:
        "201":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  meddelande:
                    type: string
                    example: "Fil uppladdad"
                  lamnadFil:
                    type: string
                    example: "fil_att_ladda_upp.xml"
                  sparadSom:
                    type: string
                    example: "Uppdrag_12345_2021-01-31T12.00.00_ABcDefGhI+JklMnOpqr1St.xml"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"


  /version/{uppdrag-id}:
    get:
      tags:
        - version
      summary: "Visa nuvarande version samt giltiga versioner för angivet uppdrag"
      operationId: "visaVersion"
      parameters:
        - in: path
          name: uppdrag-id
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  aktuellVersion:
                    type: string
                    example: "2021.1"
                  giltigaVersioner:
                    type: array
                    items:
                      type: string
                    example:
                      - "2021.1"
                      - "2019.1"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"

    put:
      tags:
        - version
      summary: "Uppdatera version för angivet uppdrag"
      operationId: "uppdateraVersion"
      parameters:
        - in: path
          name: uppdrag-id
          required: true
          schema:
            type: string
            example: "12345"
      requestBody:
        content:
          "application/json":
            schema:
              type: object
              properties:
                version:
                  description: "Ny version att uppdatera till"
                  type: string
                  example: "2021.1"
      responses:
        "200":
          description: "Lyckad operation"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: "2021.1"
                  tidigareVersion:
                    type: string
                    example: "20170225"
                  uuid:
                    $ref: "#/components/schemas/uuid"
        default:
          $ref: "#/components/responses/misslyckadOperation"


components:

  responses:
    misslyckadOperation:
      description: "Misslyckad operation"
      content:
        "application/json":
          schema:
            $ref: "#/components/schemas/misslyckadOperation"

  schemas:

    misslyckadOperation:
      type: object
      properties:
        kod:
          description: "Felkod, för mer information om felkoder, se [här](https://www.statenspersonadressregister.se/master/start/teknisk-info/program-till-program/filtransport/granssnitt/)"
          type: string
          example: "Client.OgiltigParameter"
        beskrivning:
          description: "Beskrivning av felet"
          type: string
          example: "Hittar inte en fil med namnet: filSomEjFinns.xml.zip"
        uuid:
          $ref: "#/components/schemas/uuid"
        httpStatus:
          description: "HTTP-kod"
          type: string
          example: "404"

    utfil:
      type: object
      properties:
        uppdragId:
          type: string
          example: "12345"
        filnamn:
          type: string
          example: "SPARAvisering_20220131123456_SPAR50001-12345.xml.zip"
        status:
          type: string
          enum: [ "NY", "HAMTAD", "BORTTAGEN" ]
          example: "NY"
        url:
          description: "Sökväg för att visa information om utfilen. Visas endast vid listning av utfiler"
          type: string
          example: "/utfil/SPARAvisering_20220131123456_SPAR50001-12345.xml.zip"
        skapadDatum:
          type: string
          format: date
          example: "2022-01-01"

    infilGemensam:
      type: object
      properties:
        uppdragId:
          type: string
          example: "12345"
        filnamn:
          description: "SPAR:s interna namn på filen"
          type: string
          example: "Uppdrag_12345_2021-01-31T12.00.00_ABcDefGhI+JklMnOpqr1St.xml"
        status:
          type: string
          enum: [ "MOTTAGEN", "VALIDERAD", "INKORREKT", "BORTTAGEN" ]
          example: "VALIDERAD"
        url:
          description: "Sökväg för att visa information om infilen"
          type: string
          example: "/infil/Uppdrag_12345_2021-01-31T12.00.00_ABcDefGhI+JklMnOpqr1St.xml"
        uppladdadFilNamn:
          description: "Kundens namn på fil som laddades upp till SPAR"
          type: string
          example: "fil_att_ladda_upp.xml.zip"
        uppladdadDatum:
          type: string
          format: date
          example: "2022-01-31"
        antalFunna:
          description: "Antal id-nummer från infil som hittats i SPAR"
          type: integer
          example: 10
        avvikelser:
          type: object
          properties:
            antalSaknade:
              description: "Antal id-nummer från infil som saknas i SPAR"
              type: integer
              example: 2
            antalAvregistrerade:
              description: "Antal id-nummer från infil som är avregistrerade i SPAR"
              type: integer
              example: 2
            antalDubbletter:
              description: "Antal dubbletter i infil"
              type: integer
              example: 2

    infilEnskild:
      allOf:
        - $ref: "#/components/schemas/infilGemensam"
        - type: object
          properties:
            felrapport:
              description: "Samtliga fel som upptäckts i infilen. Visas endast i information om enskild infil"
              type: array
              items:
                type: string
              example:
                - "Uppdragsid i infilen (null) är inte korrekt"
                - "Kundnumret i infilen (null) är inte korrekt"
                - "Uppdragstypen för infilen (OKAND) stämmer inte överens med uppdragstypen (Avisering)"

    infilILista:
      allOf:
        - $ref: "#/components/schemas/infilGemensam"
        - type: object
          properties:
            felmeddelande:
              description: "Det första av potentiellt flera fel i infilen. Visas endast vid listning av infiler"
              type: string
              example: "Uppdragsid i infilen (null) är inte korrekt"

    avvikelseSamling:
      description: "Saknade, avregistrerade och dubbletter av id-nummer i infil"
      type: object
      properties:
        saknas:
          $ref: "#/components/schemas/avvikelse"
        avregistrerade:
          $ref: "#/components/schemas/avvikelse"
        dubbletter:
          type: integer
          example: 2

    avvikelse:
      type: object
      properties:
        antal:
          type: integer
          example: 2
        idNummer:
          type: array
          items:
            type: string
          example:
          - "193806099101"
          - "194001079120"

    uuid:
      description: "Unikt id för anropet"
      type: string
      example: "76656761-6e34-646a-7572656e0d0a"