openapi: 3.0.3
info:
  title: Fund Submissions API
  description: API til að skila inn upplýsingum um skilagreinar
  version: 1.0.0
  contact:
    name: Skilagrein API Support
tags:
  - name: fund-payments
    description: Aðgerðir skilagreina
  - name: fund-entities
    description: Aðgerðir sjóðaeininga
security:
  - bearerAuth: []
  - basicAuth: []
  - {}
paths:
  /fund-payments:
    post:
      tags:
        - fund-payments
      summary: Skila inn skilagrein
      description: Skila inn upplýsingum um skilagreinar til vinnslu
      operationId: createFundPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundPaymentSubmission'
      responses:
        '201':
          description: Búið til - Skilagrein móttekin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
        '400':
          description: Villa í beiðni - Ógild beiðni
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
        '422':
          description: Hafnað - Skilagrein var hafnað vegna villuprófunar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
  /fund-payments/{transactionId}:
    delete:
      tags:
        - fund-payments
      summary: Bakfæra skilagrein
      description: Bakfæra (afturkalla) áður innsenda skilagrein í heild sinni út frá `transactionId`. Sjóðir geta sett eigin business-reglur um hvenær bakfærsla er leyfð (t.d. ekki hægt að bakfæra skilagrein sem þegar hefur verið bókuð).
      operationId: reverseFundPayment
      parameters:
        - name: transactionId
          in: path
          required: true
          description: '`transactionId` skilagreinarinnar sem á að bakfæra'
          schema:
            type: string
          example: txn-123456789
      responses:
        '200':
          description: OK - Skilagrein bakfærð
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
        '403':
          description: Aðgangur bannaður - Aðili hefur ekki heimild til að bakfæra þessa skilagrein
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
        '404':
          description: Fannst ekki - Engin skilagrein fannst með uppgefnu `transactionId`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
        '409':
          description: Árekstur - Ekki hægt að bakfæra skilagrein (þegar bókuð eða þegar bakfærð). Sjá nánar í `issues`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
  /fund-payments/validation:
    post:
      x-optional: true
      tags:
        - fund-payments
      summary: Villuprófa upplýsingar í skilagreinum
      description: Valkvæður endapunktur fyrir villuprófun á prufuskeyti. Innheimtuaðilar geta valið að útfæra þetta ekki.
      operationId: validateFundPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundPaymentSubmission'
      responses:
        '201':
          description: Búið til - Skilagrein móttekin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
        '400':
          description: Villa í beiðni - Ógild beiðni
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
        '422':
          description: Hafnað - Skilagrein var hafnað vegna villuprófunar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundPaymentResponse'
  /fund-entities:
    get:
      tags:
        - fund-entities
      summary: Sækja studda sjóði
      description: Skilar sjóðum sem innheimtuaðili tekur við ásamt tegundum sjóðafærslna sem eru í boði fyrir þá sjóði
      operationId: getFundEntities
      responses:
        '200':
          description: Listi af sjóðum
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FundEntity'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token í Authorization haus. Innheimtuaðili gefur út aðgangslykla og auglýsir hvernig á að fá þá (tokenUrl, scope, aðgangstengilið) í gegnum `/.well-known/skilagrein-configuration` uppgötvunarendapunktinn
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auðkenning. Notandanafn og lykilorð fást frá innheimtuaðila utan kerfis
  schemas:
    FundPaymentSubmission:
      type: object
      required:
        - transactionId
        - employerNationalId
        - currency
        - paymentEntryGroups
        - summaries
      properties:
        transactionId:
          type: string
          description: Einkvæmt færsluauðkenni
          example: txn-123456789
        employerNationalId:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^\d{10}$
          description: Kennitala launagreiðanda, án bandstriks
        currency:
          type: string
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
          description: Myntkóði - ISO 4217 3-stafa alphabetic code (t.d. ISK, EUR, USD). ISK er almennur myntkóði í tækniforskrift
          default: ISK
          example: null
        paymentEntryGroups:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEntryGroup'
          minItems: 1
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/Summary'
    PaymentEntryGroup:
      type: object
      required:
        - nationalId
        - employeeTransactionRef
        - periodFrom
        - periodTo
        - paymentEntries
      properties:
        nationalId:
          type: string
          description: Kennitala launþega, án bandstriks
          example: '0987654321'
        employeeTransactionRef:
          type: string
          description: Færslunúmer launþega - skyldubundinn reitur
          example: emp-ref-123
        periodFrom:
          type: string
          format: date
          description: Upphafsdagur launatímabils - skyldubundinn reitur
          example: '2024-01-01'
        periodTo:
          type: string
          format: date
          description: Lokadagur launatímabils - skyldubundinn reitur
          example: '2024-01-31'
        paymentEntries:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEntry'
          minItems: 1
    PaymentEntry:
      type: object
      required:
        - entityType
        - entityNo
        - amount
        - amountPayrollPercentage
      properties:
        entityType:
          type: string
          description: Tegund sjóðafærslu - stutt auðkenni
          example: L
        entityNo:
          type: string
          description: Sjóðsnúmer - númer sjóðs (SAL)
          example: '1005'
        date:
          type: string
          format: date
          description: Dagsetning útborgunar - valkvæður reitur
          example: '2024-02-01'
        amount:
          type: number
          description: Fjárhæð framlags
          example: 50000
        amountPayrollPercentage:
          type: number
          description: Hlutfall af launastofni - skyldubundinn prósentureitur
          example: 0.05
        additionalAttributes:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalAttribute'
          description: Dýnamískir sjóðasértækir viðbótarreitir. Hver sjóður skilgreinir hvaða reitir eru studdir og villuprófunarreglur þeirra í `entityTypeRules.additionalAttributes` á `/fund-entities`.
          example:
            - name: salarySymbol
              value: '001'
            - name: daysAtSea
              value: '12'
            - name: employmentRatio
              value: '1.0'
            - name: salaryTable
              value: A
            - name: salaryCategory
              value: CAT1
            - name: salarySubCategory
              value: SUB1
            - name: additionalAmount
              value: '0'
    AdditionalAttribute:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: Heiti viðbótarreits eins og sjóður skilgreinir í `entityTypeRules.additionalAttributes`
          example: salarySymbol
        value:
          type: string
          description: Gildi viðbótarreits sem strengur. Innheimtuaðili túlkar gildið skv. `type` reglu fyrir reitinn
          example: '001'
    Summary:
      type: object
      required:
        - entityNo
        - entityType
        - amountSum
      properties:
        entityNo:
          type: string
          description: Sjóðsnúmer - númer sjóðs (SAL)
          example: '1005'
        entityType:
          type: string
          description: Tegund sjóðafærslu
          example: L
        entityName:
          type: string
          description: Nafn sjóðs - valkvæður reitur
          example: Pension Fund A
        amountSum:
          type: number
          description: Summa framlags
          example: 0
    FundPaymentResponse:
      type: object
      required:
        - transactionId
        - response
        - responseId
        - postedAmount
        - issues
      properties:
        transactionId:
          type: string
          description: Færslunúmer skilagreinar
          example: txn-123456789
        response:
          type: string
          enum:
            - ACCEPTED
            - ACCEPTED_WITH_COMMENTS
            - REJECTED
            - REVERSED
          description: Staðlaður svarkóði. ACCEPTED þegar skilagrein er samþykkt, ACCEPTED_WITH_COMMENTS þegar skilagrein er móttekin með athugasemdum, REJECTED þegar skilagrein er hafnað vegna villuprófunar (athugasemdir listaðar undir "issues"), REVERSED þegar áður innsend skilagrein hefur verið bakfærð með DELETE
          example: ACCEPTED
        responseId:
          type: string
          description: Einkvæmt númer
          example: REF-123456
        postedAmount:
          type: number
          description: Upphæð
          example: 0
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
          description: Listi af villum og athugasemdum. Notað þegar svar er ACCEPTED_WITH_COMMENTS eða REJECTED (villur). Tómur listi þegar svar er ACCEPTED
          example: []
    Issue:
      type: object
      required:
        - severity
        - message
      properties:
        severity:
          type: string
          enum:
            - warning
            - error
          description: Þyngd stigs vandamáls
          example: error
        message:
          type: string
          description: Villu- eða viðvörunarskilaboð
          example: Invalid national ID format
        employeeTransactionRef:
          type: string
          description: Færslunúmer launþega
          example: emp-ref-123
        entityType:
          type: string
          description: Tegund aðila
          example: fund
        entityNo:
          type: string
          description: Sjóðsnúmer - númer sjóðs skv. merkingum SAL
          example: '1005'
    FundEntity:
      type: object
      required:
        - entityNo
        - entityTypeRules
      properties:
        entityNo:
          type: string
          description: Auðkenni sjóðs (SAL númer)
          example: '1234'
        entityTypeRules:
          type: array
          items:
            $ref: '#/components/schemas/EntityTypeRule'
          description: Tegundir sjóðafærslna í boði fyrir þennan sjóð ásamt sjálfgefnum prósentum
    EntityTypeRule:
      type: object
      required:
        - entityType
        - defaultPercentage
      properties:
        entityType:
          type: string
          description: Tegund sjóðafærslu - stutt auðkenni
          example: A1
        defaultPercentage:
          type: number
          description: Sjálfgefið hlutfall fyrir þessa tegund sjóðafærslu
          example: 0.12
        additionalAttributes:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalAttributeRule'
          description: Lýsigögn um dýnamíska viðbótarreiti sem sjóður tekur við sem hluti af `paymentEntry.additionalAttributes` fyrir þessa sjóðafærslutegund. Auður listi eða reiti sleppt þýðir að engir viðbótarreitir eru studdir
    AdditionalAttributeRule:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Heiti viðbótarreits. Verður að passa við `name` í `paymentEntry.additionalAttributes` færslum
          example: salarySymbol
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - date
          description: Týpan sem innheimtuaðili túlkar `value` strenginn sem
          example: string
        description:
          type: string
          description: Lýsing á reitnum
          example: Launatákn (B-deild)
        required:
          type: boolean
          default: false
          description: Hvort reiturinn sé skyldubundinn á öllum samsvarandi `paymentEntry` færslum
          example: false
        allowedValues:
          type: array
          items:
            type: string
          description: Valkvæður lokaður listi yfir leyfileg gildi. Ef tilgreindur verður `value` að vera eitt af þessum
          example:
            - '001'
            - B
            - V
            - '032'