openapi: '3.0.2'
info:
  title: WebUntis Class Register Absences extern API documentation
  description: 'WebUntis API for external usage of platform applications to retrieve student absences information.'
  version: '1.0.0'
  contact:
    name: Untis GmbH
    url: 'https://www.untis.at'
    email: support@untis.at
paths:
  /api/rest/extern/v1/classreg/students/absencetimes:
    get:
      summary: Retrieves a student absence times details (within the bounds of a single school year).
      tags:
        - class-reg-ext-student-absence
      operationId: getStudentAbsenceTimes
      parameters:
        - name: start
          description: Lower date-time range boundary of requested absences in ISO 8601 format. Must be in the same school year as end.
          in: query
          required: true
          schema:
            type: string
            format: date-time
            example: "2022-02-21T00:00:00"
        - name: end
          description: Upper date-time range boundary of requested absences in ISO 8601 format. Must be in the same school year as start.
          in: query
          required: true
          schema:
            type: string
            format: date-time
            example: "2022-02-22T00:00:00"
        - name: studentExternKey
          description: WebUntis student external ID. Either className or studentExternKey must be provided.
          in: query
          schema:
            type: string
            example: "001"
        - name: className
          description: WebUntis name of the class. Either className or studentExternKey must be provided.
          in: query
          schema:
            type: string
            example: "1-AHELE"
      responses:
        "200":
          description: Success
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/ClassRegExtStudentsAbsenceTimesRespDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "400":
          description: Client error - bad request
        "500":
          description: Server error
components:
  schemas:
    ClassRegExtStudentsAbsenceTimesRespDto:
      type: object
      required:
        - students
      properties:
        students:
          items:
            $ref: "#/components/schemas/ClassRegExtStudentAbsenceTimesDto"
          type: array
    ClassRegExtStudentAbsenceTimesDto:
      type: object
      description: Student and associated absence statistitcs.
      required:
        - studentId
        - totals
        - excusedTotals
        - unexcusedTotals
        - absenceTimes
      properties:
        studentId:
          description: WebUntis student's internal ID.
          format: int64
          type: integer
        studentExternKey:
          description: External ID of the student.
          type: string
        totals:
          $ref: "#/components/schemas/ClassRegExtStudentAbsenceTimesStatsDto"
        excusedTotals:
          $ref: "#/components/schemas/ClassRegExtStudentAbsenceTimesStatsDto"
        unexcusedTotals:
          $ref: "#/components/schemas/ClassRegExtStudentAbsenceTimesStatsDto"
        absenceTimes:
          items:
            $ref: "#/components/schemas/ClassRegExtStudentAbsencePeriodTimeDto"
          type: array
    ClassRegExtStudentAbsenceTimesStatsDto:
      type: object
      description: Wrapper for student absences statistics. It is intended to be associated
        with particular absences statistics category (totals, excusedTotals, unexcusedTotals).
      required:
        - days
        - hours
        - delays
      properties:
        days:
          $ref: "#/components/schemas/ClassRegExtStudentAbsenceTimesStatsDaysDto"
        hours:
          description: Total number of student's absenting hours (calculated according to the Class Register settings)
          format: int32
          type: integer
        delays:
          description: Total number of student's delays (number of periods which student attended partially - and so evaluated as latenesses)
          format: int32
          type: integer
    ClassRegExtStudentAbsenceTimesStatsDaysDto:
      type: object
      description: Wrapper for statistics subgroup of absenting days.
      required:
        - count
        - remainingHours
      properties:
        count:
          description: Total number of absenting days (calculated according to the Class Register settings)
          format: int32
          type: integer
        remainingHours:
          description: Total number of hours (calculated according to the Class Register settings) not resulting in absent day.
          format: int32
          type: integer
    ClassRegExtStudentAbsencePeriodTimeDto:
      type: object
      description: Absence time - period and related absence information.
      required:
        - start
        - end
        - minutes
        - subjectName
        - status
        - type
      properties:
        start:
          description: The start date-time of absence for this period in ISO 8601 format.
          example: 2019-12-23T07:45:00Z
          format: date-time
          type: string
        end:
          description: The end date-time of absence for this period in ISO 8601 format.
          example: 2019-12-23T07:45:00Z
          format: date-time
          type: string
        minutes:
          description: Total number of missed period minutes.
          format: int32
          type: integer
        subjectName:
          description: Name of the period's subject.
          type: string
        status:
          description: Excuse status of this missed period.
          type: string
        type:
          $ref: "#/components/schemas/ClassRegExtStudentAbsenceTypeEnum"
    ClassRegExtStudentAbsenceTypeEnum:
      description: Type of absence.
      type: string
      enum:
        - DELAY
        - ABSENCE