openapi: 3.0.3
info:
  title: LV - Service API v1.0.12
  description: |-
    LV Service API v1.0.12 (OpenAPI 3.0)

    Service API provided by LV service:
    - [Luvat ja Valvonta website](https://lv.ahtp.fi)

  termsOfService: https://lv.ahtp.fi/fi/kayttoehdot
  contact:
    email: tuki.lv@ely-keskus.fi
  version: v1.0.12
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
paths:
  /commondata/{externalId}/commondata:
    get:
      summary: Common data
      description: Retrieve common data related to a project part action.
      operationId: GetProjectPartCommonData
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Commondata'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/formdata:
    get:
      summary: Form data
      description: Retrieve only form data related to a project part action.
      operationId: GetProjectPartFormData
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Formdata'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/metadata:
    get:
      summary: Form metadata
      description: Retrieve only metadata related to a project part action.
      operationId: GetProjectPartMetaData
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
        '400':
          description: Invalid externalId format.
        '401':
          description: Unauthorized request
        '404':
          description: Metadata not found.
  /commondata/{externalId}:
    get:
      summary: Project part data
      description: Retrieve all necessary data related to a project part action.
      operationId: GetProjectPartData
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectPartData'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
    delete:
      summary: Delete project part action
      description: Delete a project part action.
      operationId: DeleteProjectPartAction
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/formconfig:
    get:
      summary: Form config
      description: Retrieve only form configuration related to a project part action.
      operationId: GetProjectPartFormConfig
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Formconfig'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/accesslink:
    get:
      summary: Access link
      description: Retrieve the project part action access link for authorities.
      operationId: GetProjectPartAccessLink
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLinkResponse'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/diarynumber:
    get:
      summary: Project part diary number
      description: Retrieve the diary number for a project part action.
      operationId: GetProjectPartDiaryNumber
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiaryNumberResponse'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
    put:
      summary: Update diary number for project part
      description: Update a project part diary number.
      operationId: UpdateProjectPartDiaryNumber
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Diary number update payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiaryNumber'
      responses:
        '200':
          description: Successful operation
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/status:
    get:
      summary: Project part status
      description: Retrieve the status for a project part action.
      operationId: GetProjectPartStatus
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectPartStatusResponse'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
    put:
      summary: Update status for project part
      description: Update a project part status.
      operationId: UpdateProjectPartStatus
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Status change payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusChange'
      responses:
        '200':
          description: Successful operation
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/statuses:
    get:
      summary: Available statuses for project part
      description: Retrieve all available statuses for a project part action.
      operationId: GetProjectPartStatuses
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusesResponse'
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/handlingofficers:
    put:
      summary: Update handling officers for project part
      description: Update a project part's handling officers.
      operationId: UpdateProjectPartHandlingOfficers
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Handling officer list.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Officer'
      responses:
        '200':
          description: Successful operation
        '400':
          description: Project part action not found with externalId or the externalId format is invalid.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/attachment/{fileId}:
    get:
      summary: Project part attachment metadata
      description: Retrieve metadata for a single project part attachment file.
      operationId: GetProjectPartAttachment
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
        - name: fileId
          in: path
          description: Attachment file ID.
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectPartAttachment'
        '400':
          description: File not found with fileId, project part not found with externalId, or invalid externalId format.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/attachments:
    get:
      summary: Project part attachment metadata list
      description: Retrieve project part attachment metadata.
      operationId: GetProjectPartAttachments
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectPartAttachmentsResponse'
        '400':
          description: Project part not found with externalId or invalid externalId format.
        '401':
          description: Unauthorized request
  /commondata/attachment/{externalId}/file/{fileId}:
    get:
      summary: Project part attachment file
      description: Retrieve a single project part attachment file by ID.
      operationId: GetProjectPartAttachmentFile
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
        - name: fileId
          in: path
          description: Attachment file ID.
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successful operation
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: File not found with fileId, project part not found with externalId, or invalid externalId format.
        '401':
          description: Unauthorized request
  /commondata/attachment/{externalId}/files:
    get:
      summary: Project part attachment files as zip
      description: Retrieve multiple project part attachment files as a zip archive.
      operationId: GetProjectPartAttachmentFiles
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid externalId format.
        '401':
          description: Unauthorized request
        '404':
          description: No attachments found for the project part action.
  /commondata/create-external:
    post:
      summary: Create external project part action
      description: Create an external project part action.
      operationId: CreateExternalProjectPartAction
      requestBody:
        description: External permit details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/External'
        '400':
          description: Invalid request data.
        '401':
          description: Unauthorized request
  /commondata/{externalId}/{documentType}:
    post:
      summary: Upload official attachments
      description: Upload one or more official document attachments for a project part action.
      operationId: PostProjectPartAttachments
      parameters:
        - name: externalId
          in: path
          description: Project part action external ID.
          required: true
          schema:
            type: string
            format: uuid
        - name: documentType
          in: path
          description: Common document type applied to all uploaded files.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - uploadOfficialAttachments
              properties:
                uploadOfficialAttachments:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOfficialDocumentAttachmentsResponse'
        '400':
          description: Invalid externalId, invalid documentType, invalid files, or upload validation failed.
        '401':
          description: Unauthorized request
components:
  schemas:
    Commondata:
      type: object
      properties:
        name:
          type: string
          example: TestAction A
        externalId:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        actionId:
          type: integer
          format: int32
          example: 7
        diaryNumber:
          type: string
          example: xxx-xxx-xxx
        projectPartSpecification:
          $ref: '#/components/schemas/ProjectPartSpecification'
        status:
          $ref: '#/components/schemas/ProjectPartStatus'
        handlingOfficers:
          type: array
          items:
            $ref: '#/components/schemas/Officer'
        advisorOfficers:
          type: array
          items:
            $ref: '#/components/schemas/Officer'
        transaction:
          $ref: '#/components/schemas/Transaction'
        userEmailInfo:
          $ref: '#/components/schemas/UserEmailInfo'
    ProjectPartSpecification:
      type: object
      properties:
        name:
          type: string
        translations:
          type: string
    Formconfig:
      type: object
      properties:
        formConfig:
          type: string
          example: '{"pages":[]}'
    Formdata:
      type: object
      properties:
        formData:
          type: string
          example: '{"toiminnanharjoittajaSivu":{"toiminnanharjoittajanPerustiedotOsio":{"toiminnanharjoittajanNimiTietue":"Demo, Nordea","yTunnusTietue":"-"}}}'
        attachmentMetaDatas:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentMetadata'
        infoRequests:
          $ref: '#/components/schemas/InfoRequestsResponse'
    Metadata:
      type: object
      properties:
        projectPartSpecificationName:
          type: string
          example: KEMTURVL
        projectPartName:
          type: string
          example: Asioijan itse asettama nimi
        municipalityCode:
          type: string
          example: '091'
        lvUrl:
          type: string
          example: https://lv.ahtp.fi/fi/asiointikansio/kohde/100/asiointikokonaisuus/101/lomake/200/asiointi/205
        lvUrlOfficial:
          type: string
          example: https://lv-vir.ahtp.fi/fi/seuraa/00000000-0000-0000-0000-000000000000
    AccessLinkResponse:
      type: object
      properties:
        accessLink:
          type: string
          example: https://lv-vir.ahtp.fi/fi/seuraa/00000000-0000-0000-0000-000000000000
    DiaryNumberResponse:
      type: object
      properties:
        diaryNumber:
          type: string
          example: xxx-xxx-xxx
    ProjectPartData:
      type: object
      properties:
        commonData:
          $ref: '#/components/schemas/Commondata'
        formData:
          type: string
          example: '{"toiminnanharjoittajaSivu":{"toiminnanharjoittajanPerustiedotOsio":{"toiminnanharjoittajanNimiTietue":"Demo, Nordea","yTunnusTietue":"-"}}}'
        attachmentMetaDatas:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentMetadata'
        infoRequests:
          $ref: '#/components/schemas/InfoRequestsResponse'
    StatusesResponse:
      type: object
      properties:
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/ProjectPartStatus'
    ProjectPartStatusResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ProjectPartStatus'
    ProjectPartStatus:
      type: object
      required:
        - primaryStatus
      properties:
        statusDate:
          type: string
          format: date-time
        resolutionDate:
          type: string
          format: date-time
        initiationDate:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
        completeDate:
          type: string
          format: date-time
        primaryStatus:
          $ref: '#/components/schemas/ProjectPartPrimaryStatusType'
        primaryStatusTranslations:
          type: string
          example: '{"fi":"Käsittelyssä"}'
        secondaryStatus:
          $ref: '#/components/schemas/ProjectPartSecondaryStatusType'
        secondaryStatusTranslations:
          type: string
          example: '{"fi":"Täydennyspyyntö"}'
    Officer:
      type: object
      properties:
        name:
          type: string
          example: Ville Virkamies
        role:
          type: string
          example: Käsittelijä
        phone:
          type: string
          example: '0001234568'
        handlingOrganization:
          type: string
          example: AVI
        virtuOrganization:
          type: string
          example: testivirasto.fi
        virtuId:
          type: string
          example: vvirkamies
        email:
          type: string
          example: ville.virkamies@testivirasto.fi
    Transaction:
      type: object
      properties:
        transactionName:
          type: string
        objectOfControlName:
          type: string
        municipality:
          $ref: '#/components/schemas/Municipality'
    Municipality:
      type: object
      properties:
        name:
          type: string
          example: Helsinki
        code:
          type: string
          example: '91'
    UserEmailInfo:
      type: object
      properties:
        creatorEmail:
          type: string
        senderEmail:
          type: string
    ProjectPartAttachment:
      type: object
      properties:
        attachmentMetadata:
          $ref: '#/components/schemas/AttachmentMetadata'
    ProjectPartAttachmentsResponse:
      type: object
      properties:
        attachmentMetadatas:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentMetadata'
    AttachmentMetadata:
      type: object
      properties:
        id:
          type: integer
          format: int32
        fileName:
          type: string
        extension:
          type: string
        mimeType:
          type: string
        location:
          type: string
        hash:
          type: string
        lastModifiedTime:
          type: string
          format: date-time
        description:
          type: string
    InfoRequestsResponse:
      type: object
      properties:
        infoRequests:
          type: array
          items:
            $ref: '#/components/schemas/InfoRequestItem'
    InfoRequestItem:
      type: object
      properties:
        message:
          type: string
        dueDate:
          type: string
          format: date-time
        createdDate:
          type: string
          format: date-time
        response:
          type: string
        responseDate:
          type: string
          format: date-time
        status:
          type: string
    ProjectPartPrimaryStatusType:
      description: Project part primary status enum serialized as upper snake case.
      type: string
      enum:
        - NONE
        - NEW
        - DRAFT
        - SENT
        - RECEIVED
        - IN_PROGRESS
        - ACCEPTED
        - ACCEPTED_IN_EFFECT
        - REJECTED
        - REJECTED_IN_EFFECT
        - EXPIRED
        - CANCELED
        - DONE
        - INADMISSIBLE
        - RESOLVED
        - PARTIALLY_GRANTED
        - RECEIVED_NO_FURTHER_ACTION
        - REGISTERED
        - PROCESSED
    ProjectPartSecondaryStatusType:
      description: Project part secondary status enum serialized as upper snake case.
      type: string
      enum:
        - NONE
        - INFO_REQUEST
        - INFO_REQUEST_ANSWERED
        - HEARING
        - HEARING_FINISHED
        - APPLICATION_REVIEW_REQUEST_FOR_AUTHORITIES
        - APPLICATION_REVIEWED
        - REQUEST_FOR_APPLICANTS_RESPONSE
        - RESPONSE_GIVEN_BY_APPLICANT
        - TRANSFER_EXTERNAL_SERVICE_TRIGGER_SENT
        - TRANSFER_EXTERNAL_SERVICE_IN_PROGRESS
        - TRANSFER_EXTERNAL_SERVICE_ERROR
        - TRANSFER_EXTERNAL_SERVICE_DONE
        - INFO_REQUEST_ANSWER_SENT
        - COMPLETE
    DiaryNumber:
      type: object
      properties:
        diaryNumber:
          type: string
    StatusChange:
      type: object
      required:
        - status
      properties:
        resolutionDate:
          type: string
          format: date-time
        initiationDate:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
        status:
          type: string
          description: Primary status value in the same upper snake case format as `ProjectPartPrimaryStatusType`.
        secondaryStatus:
          type: string
          description: Secondary status value in the same upper snake case format as `ProjectPartSecondaryStatusType`.
        url:
          type: string
        additionalInformation:
          type: string
        senderName:
          type: string
        completeDate:
          type: string
          format: date-time
    External:
      type: object
      properties:
        externalId:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
    CreateExternalRequest:
      type: object
      required:
        - projectPartSpecificationName
        - projectPartName
        - businessIdOrSSN
        - externalProjectPartUrl
      properties:
        projectPartSpecificationName:
          type: string
          description: Project part specification name.
          example: KEMTURVL
        projectPartName:
          type: string
          description: Project part name.
          example: External Permit Example
        businessIdOrSSN:
          type: string
          description: Business ID or social security number.
          example: 1234567-8
        externalProjectPartUrl:
          type: string
          description: URL for the external permit.
          example: https://external-system.example.com/task/123
    CreateOfficialDocumentAttachmentsResponse:
      type: object
      properties:
        attachmentMetadatas:
          type: array
          items:
            $ref: '#/components/schemas/UploadedAttachmentMetadata'
        officialDocumentTypes:
          type: object
          additionalProperties:
            type: string
    UploadedAttachmentMetadata:
      type: object
      properties:
        fileId:
          type: integer
          format: int32
        fileName:
          type: string
        fileType:
          type: string
        path:
          type: string
        lastModified:
          type: string
          format: date-time
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
