openapi: 3.0.3
info:
  title: Service Discovery
  description: Well-known endapunktur fyrir uppgötvun þjónustu innheimtuaðila
  version: 1.0.0
  contact:
    name: Skilagrein API Support
tags:
  - name: discovery
    description: Uppgötvun þjónustu
paths:
  /.well-known/skilagrein-configuration:
    get:
      tags:
        - discovery
      summary: Sækja stillingar innheimtuaðila
      description: |
        Skilar stillingum innheimtuaðila; tiltækar API útgáfur, auðkenningarupplýsingar og staðsetningar endapunkta. Þessi endapunktur krefst ekki auðkenningar.
      operationId: getCollectorConfiguration
      responses:
        '200':
          description: Stillingar innheimtuaðila
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectorConfiguration'
              example:
                schemaVersion: '1.0'
                collectorId: '1234'
                apiVersions:
                  - apiVersion: '1.0'
                    validFrom: '2026-01-01'
                    validTo: null
                    endpoint: https://api.example.is/v1/fund-payments
                    validationEndpoint: https://api.example.is/v1/fund-payments/validation
                    openApiUrl: https://api.example.is/v1/openapi.json
                    authentication:
                      type: oauth2_client_credentials
                      tokenUrl: https://auth.example.is/connect/token
                      scope: skilagrein
                      credentialContact:
                        description: Contact the collector to obtain OAuth client credentials (client ID and secret)
                        email: api@example.is
                        url: https://developer.example.is/access
components:
  schemas:
    CollectorConfiguration:
      type: object
      required:
        - schemaVersion
        - collectorId
        - apiVersions
      properties:
        schemaVersion:
          type: string
          description: Útgáfunúmer
          example: '1.0'
        collectorId:
          type: string
          description: Auðkenni innheimtuaðila (SAL númer)
          example: '1234'
        apiVersions:
          type: array
          items:
            $ref: '#/components/schemas/ApiVersionConfig'
          minItems: 1
          description: Tiltækar API útgáfur og endapunktar þeirra
    AuthenticationConfig:
      oneOf:
        - $ref: '#/components/schemas/OAuth2ClientCredentialsAuth'
        - $ref: '#/components/schemas/BasicAuth'
        - $ref: '#/components/schemas/NoAuth'
      discriminator:
        propertyName: type
        mapping:
          oauth2_client_credentials: '#/components/schemas/OAuth2ClientCredentialsAuth'
          basic: '#/components/schemas/BasicAuth'
          none: '#/components/schemas/NoAuth'
    OAuth2ClientCredentialsAuth:
      type: object
      required:
        - type
        - tokenUrl
        - scope
        - credentialContact
      properties:
        type:
          type: string
          enum:
            - oauth2_client_credentials
          description: OAuth 2.0 client credentials flæði
        tokenUrl:
          type: string
          format: uri
          description: Slóð til að sækja aðgangslykla
          example: https://auth.example.is/connect/token
        scope:
          type: string
          description: OAuth scope sem þarf að tilgreina við beiðni um aðgangslykla
          example: skilagrein
        credentialContact:
          $ref: '#/components/schemas/CredentialContact'
    BasicAuth:
      type: object
      required:
        - type
        - credentialContact
      properties:
        type:
          type: string
          enum:
            - basic
          description: HTTP Basic auðkenning. Notandanafn og lykilorð eru send í Authorization haus á hverri beiðni
        credentialContact:
          $ref: '#/components/schemas/CredentialContact'
    NoAuth:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - none
          description: Engin auðkenning. Endapunkturinn er opinn
    CredentialContact:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          description: Leiðbeiningar um hvernig á að fá aðgangsupplýsingar (t.d. client ID og secret)
          example: Contact the collector to obtain OAuth client credentials (client ID and secret)
        email:
          type: string
          format: email
          description: Netfang til að óska eftir aðgangsupplýsingum
          example: api@example.is
        url:
          type: string
          format: uri
          description: Slóð á skráningarsíðu eða þróunargátt fyrir aðgangsupplýsingar
          example: https://developer.example.is/access
    ApiVersionConfig:
      type: object
      required:
        - apiVersion
        - validFrom
        - endpoint
        - openApiUrl
        - authentication
      properties:
        apiVersion:
          type: string
          description: Útgáfuauðkenni API
          example: '1.0'
        validFrom:
          type: string
          format: date
          description: Dagsetning sem útgáfa tekur gildi frá
          example: '2026-01-01'
        validTo:
          type: string
          format: date
          nullable: true
          description: Dagsetning sem útgáfa gildir til. Null þýðir enn í gildi
          example: null
        endpoint:
          type: string
          format: uri
          description: Grunnslóð endapunkts fyrir þessa API útgáfu
          example: https://api.example.is/v1/fund-payments
        validationEndpoint:
          type: string
          format: uri
          description: Slóð villuprófunar-endapunkts fyrir þessa API útgáfu. Ef reiturinn er skilinn eftir auður styður innheimtuaðili ekki villuprófun fyrir þessa útgáfu
          example: https://api.example.is/v1/fund-payments/validation
        openApiUrl:
          type: string
          format: uri
          description: Slóð á OpenAPI tækniforskrift fyrir þessa API útgáfu
          example: https://api.example.is/v1/openapi.json
        authentication:
          $ref: '#/components/schemas/AuthenticationConfig'