openapi: 3.0.3
info:
  title: Build Permit Nova API (Bygglov Sokigo Nova)
  description: |
    REST API for automatically publishing information objects as pages or articles in SiteVision.
    
    The Build Permit Nova application receives information objects via HTTP calls and creates 
    corresponding pages with configured metadata and placement in SiteVision.
  version: 1.1.0
  contact:
    name: Soleil IT
    url: https://soleil.se
  license:
    name: Proprietary
    
servers:
  - url: https://marketplace.soleil.se/rest-api/build-permit-nova
    description: Application base URL (relative to SiteVision site)

paths:
  /:
    get:
      summary: Health check
      description: |
        Returns a welcome message to confirm that the API is available

        **Authentication Required**: This endpoint requires basic HTTP authentication.
      operationId: healthCheck
      security:
        - basicAuth: []
      tags:
        - Health
      responses:
        '200':
          description: API is available
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Hi and welcome to the Build Permit - Nova app!"
                required:
                  - message

  /v1/publish:
    post:
      summary: Publish information object
      description: |
        Publishes an information object as a new page or article in SiteVision.
        
        The object will be placed according to the configured location rules based on the `type` field,
        and metadata will be mapped according to the application configuration.
        
        **Authentication Required**: This endpoint requires basic HTTP authentication.
      operationId: publishInformationObject
      security:
        - basicAuth: []
      tags:
        - Publishing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
            examples:
              basic_example:
                summary: Permit proclamation information object
                value:
                  origin: "Sokigo Nova"
                  type: 101
                  data:
                    id: "1234-56-78"
                    title: "Exempel på informationsobjekt"
                    content: "Detta är ett exempel på innehåll i ett informationsobjekt."
                    estate: "Bryggudden 1:2"
                    responseDate: 1705705200000
                    publishDate: 1706137200000
                    publishEndDate: 1735686000000
              full_example:
                summary: Permit decision information object
                value:
                  origin: "Sokigo Nova"
                  type: 102
                  data:
                    id: "1234-56-78"
                    title: "Exempel på informationsobjekt"
                    content: "Detta är ett exempel på innehåll i ett informationsobjekt."
                    estate: "Bryggudden 1:2"
                    decision: "Beslutet fattades den 2024-01-15."
                    decisionNumber: "98-12-1444"
                    decisionDate: 1705705200000
                    publishDate: 1706137200000
                    publishEndDate: 1735686000000
                    externalUrl: "https://example.com/more-info"
      responses:
        '200':
          description: Information object published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishResponse'
              example:
                success: true
        '400':
          description: Bad request - Invalid or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_origin:
                  summary: Missing origin field
                  value:
                    message: "Field origin is required"
                missing_data:
                  summary: Missing data field
                  value:
                    message: "Field data is required"
                missing_data_id:
                  summary: Missing data.id field
                  value:
                    message: "Field data.id is required"
                invalid_location:
                  summary: Invalid location configuration
                  value:
                    message: "No valid location configured found for the provided type"
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: "Authentication required"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                server_error:
                  summary: Server error
                  value:
                    message: "Misslyckades att skapa ny sida för Example Title"

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        Basic HTTP authentication is required to access the API.
        Use your SiteVision username and password for authentication.
        
        Example:
        ```
        curl -X POST "https://marketplace.soleil.se/rest-api/build-permit-nova/v1/publish" \
             -u "username:password" \
             -H "Content-Type: application/json" \
             -d '{ ... }'
        ```
  
  schemas:
    PublishRequest:
      type: object
      required:
        - origin
        - type
        - data
      properties:
        origin:
          type: string
          description: Origin of the information object
          example: "Sokigo Nova"
        type:
          type: integer
          description: |
            Type of information object that can be one of the following number values:
            - 100: Permit proclamation (Kungörelse)
            - 101: Neighbor consultation (Grannhörande)
            - 102: Permit decision (Beslut)
            - 199: Other (Övrigt)
          example: 101
        lang:
          type: string
          description: |
            Language code for the content (e.g., "en" for English, "sv" for Swedish). It is optional
            and if not provided the configured language on the receiving end will be used. This
            parameter should normally not be needed unless it is important to override the language.
            Supported languages are:
            - "en": English
            - "sv": Swedish
            - "no": Norwegian
            - "de": German
            - "fr": French
            - "es": Spanish
          example: "sv"
        data:
          $ref: '#/components/schemas/InformationObjectData'
    
    InformationObjectData:
      type: object
      required:
        - id
        - title
        - content
        - publishDate
        - publishEndDate
      properties:
        id:
          type: string
          description: Unique identifier for the information object
          example: "Diarienummer 1234-56-78"
        title:
          type: string
          description: Title for the created page
          example: "Exempel på informationsobjekt"
        content:
          type: string
          description: Content of the information object
          example: "Detta är ett exempel på innehåll i ett informationsobjekt."
        estate:
          type: string
          description: Property/estate information
          example: "Bryggudden 1:2"
        decision:
          type: string
          description: Decision information
          example: "Beslutet fattades den 2024-01-15."
        decisionNumber:
          type: string
          description: Decision number
          example: "1234-56-78"
        decisionDate:
          type: integer
          format: int64
          description: Decision date as Unix timestamp in milliseconds
          example: 1705705200000
        responseDate:
          type: integer
          format: int64
          description: Response date as Unix timestamp in milliseconds
          example: 1705705200000
        publishDate:
          type: integer
          format: int64
          description: Publish date as Unix timestamp in milliseconds
          example: 1706137200000
        publishEndDate:
          type: integer
          format: int64
          description: End date for publishing as Unix timestamp in milliseconds
          example: 1735686000000
        externalUrl:
          type: string
          description: External URL related to the information object
          example: "https://example.com/more-info"

    PublishResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: Indicates if the operation was successful
          example: true



    ErrorResponse:
      type: object
      required:
        - error
      properties:
        message:
          type: string
          description: Error message describing what went wrong
          example: "Field origin is required"
        body:
          type: string
          description: Additional details about the error. Mostly null.

tags:
  - name: Health
    description: Health check operations
  - name: Publishing
    description: Information object publishing operations