webuntis

webuntis

JSON-RPC

Webuntis is using a json-rpc endpoint implemented in Java (jsonrpc4j). This library is using the mobile.webuntis.com server with the 2017 methods to get more data like cancelled or irregular periods.

Request

Inquiries should be structured as follows:

1) body

{
  id: 0,
  jsonrpc: "2.0",
  method: "yourMethod",
  params: []
}

2) headers; this header is completely sufficient: Content-Type: application/json

Authentication

A user account is required for all inquiries, which makes it difficult to test this library correctly.

I'm adding this to every request (except the shared_secret method):

{
  "user": username,
  "otp": generated one-time password,
  "clientTime": system time in milliseconds
}

The api never saves your password but have to remember your shared app secret. You can get your school-id and secret at: https://mese.webuntis.com/WebUntis/index.do#/basic/profile?selectedTab=access. Just click on show QR-code to display your data.

Methods

Timetable

getTimetable2017

  • id: student or class id (e.g. 889)
  • type: STUDENT / CLASS
  • startDate: begin of the time range (e.g. 2020-03-13)
  • endDate: end of this range

You can use Elixir's build in dates here or just type your date as string in the iso-standard as a string.

Example for displaying the timetable of the student for the current day:

today = Date.utc_today()
Webuntis.timetable_student(889, today, today)

Homework

getHomeWork2017

  • id: student id
  • type: STUDENT
  • startDate: begin of the time range (e.g. 2020-03-13)
  • endDate: end of this range

Get all homework for the time range. I don't have structs for them yet...

Messages

getMessagesOfDay2017

  • date: date for the messages

Returns the news and messages of the day. Same as homework, I don't have structs for them yet...

Absences

getStudentAbsences2017

  • startDate: begin of the time range (e.g. 2020-03-13)
  • endDate: end of this range
  • includeExcused: display excused absences? (boolean)
  • includeUnExcused: display unexcused absences?

Displays all absences of a studnet for a school year, for example. See Webuntis.Struct.Absence and Webuntis.Struct.Excuse for more informations about the fields.

Userdata

getUserData2017

No extra params

This returns a lot of data:

  • master data (used internal to resolve elements)
  • settings
  • messenger settings
  • "real" user data (e.g. student id, display name etc.)

Response

The endpoint answers in this structure:

{
  "jsonrpc": "2.0",
  "id": "",
  "result": { result }
}

All Webuntis function in the main module are encoding this json data, put it into maps and usally into structs like Webuntis.Struct.Teacher or Webuntis.Struct.Period.