jecnarozvrh/web/content/posts/api/v3/index.md

---
title: "API Dokumentace - Verze 3"
date: 2026-03-17
tags: ["api", "docs", "v3"]
hiddenInHomelist: true
---

Tato stránka detailně popisuje **Verzi 3 (v3)** API Ječná Rozvrh. Endpoint poskytuje strukturovaná data o suplování, absencích, událostech a rezervacích místností.

## Endpoint: `GET /versioned/v3`

Toto je hlavní endpoint, který poskytuje veškerá aktuální data.

### Struktura Odpovědi

Odpověď je formátována jako JSON objekt obsahující dva hlavní uzly: `schedule` (samotná data rozvrhu) a `status` (metadata o rozvrhu).

<details>
<summary>Zobrazit příklad struktury odpovědi</summary>

```json
{
  "schedule": { /* objekt denních rozvrhů */ },
  "status": { /* objekt stavu a metadat */ }
}
```
</details>

---

### Datové Struktury

#### Sekce: `schedule`

Tato sekce je objekt, kde každý klíč představuje datum ve formátu `YYYY-MM-DD` (např. `"2026-03-17"`). Hodnotou je objekt reprezentující data pro daný den. Tento objekt obsahuje klíče: `info`, `changes`, `absence`, `takesPlace` a `reservedRooms`.

##### `info`

Objekt obsahující dodatečné informace o stavu rozvrhu pro daný den.

  - `inWork` (boolean): Nabyde hodnoty `true`, pokud se s daným dnem ze strany školy ještě manipuluje (tzv. "příprava"). Znamená to, že data pro tento den **nemusí být finální** a mohou se ještě měnit.

##### `changes`

Objekt obsahující změny v rozvrhu pro jednotlivé třídy.

  - **Klíč:** Název třídy (např. `"A1"`, `"C4a"`).
  - **Hodnota:** Pole o **přesně 10 prvcích**, které reprezentují 1. až 10. vyučovací hodinu.
    - `null`: Pro danou hodinu není evidována žádná změna (výuka probíhá normálně, nebo hodina není v rozvrhu).
    - `Objekt`: Záznam o změně nebo specifické informaci.

Struktura objektu změny:

```ts
{
  text: string,               // Textový obsah změny (např. "M 5 odpadá")
  backgroundColor: string | null, // HEX kód barvy pozadí (např. "#DCEDD5")
  foregroundColor?: string,   // Volitelný HEX kód barvy textu (např. "#FF000000")
  willBeSpecified?: boolean   // True, pokud buňka značí "bude upřesněno" (obvykle žlutá barva)
}
```

<details>
<summary>Zobrazit příklad rozvrhu pro třídu A1</summary>

```json
"A1": [
  {
    "text": "M 5 Kp(Ng)",
    "backgroundColor": "#FFCCCC",
    "foregroundColor": "#FF000000"
  },
  null,
  null,
  {
    "text": "M 5 odpadá",
    "backgroundColor": "#DCEDD5",
    "foregroundColor": "#FF000000"
  },
  null,
  null,
  null,
  null,
  null,
  null
]
```
</details>

##### `absence`

Pole objektů, kde každý objekt specifikuje jednu evidovanou absenci učitele nebo změnu jeho stavu (např. exkurze). Pokud pro daný den nikdo nechybí, pole je prázdné `[]`.

Struktura objektu absence:

  - `teacher` (string | null): Celé jméno učitele (např. `"Ing. Jan Novák"`), pokud je známé.
  - `teacherCode` (string | null): Interní dvoupísmenná zkratka učitele malými písmeny (např. `"no"`).
  - `type` (string): Typ záznamu. Možné hodnoty:
    - `"wholeDay"`: Učitel chybí celý den.
    - `"single"`: Učitel chybí jednu konkrétní vyučovací hodinu.
    - `"range"`: Učitel chybí v rozmezí několika vyučovacích hodin.
    - `"exkurze"`: Učitel je mimo školu na exkurzi.
    - `"zastoupen"`: Specifický stav, kdy učitele kompletně zastupuje někdo jiný.
    - `"invalid"`: Záznam o absenci se nepodařilo zpracovat.
  - `hours` (object | number | null): Specifikuje vyučovací hodiny, kterých se záznam týká.
    - `null`: Pro typy `wholeDay`, `zastoupen`, `invalid` a často i `exkurze` (pokud je na celý den).
    - `number` (např. `3`): Pro typ `single` (týká se pouze 3. hodiny).
    - `object` (např. `{ "from": 2, "to": 4 }`): Pro typ `range` nebo částečnou `exkurze` (týká se času od 2. do 4. hodiny).
  - `zastupuje` (object | volitelné): Přítomno **pouze** u typu `"zastoupen"`. Obsahuje vnořené klíče `teacher` a `teacherCode` pro učitele, který přebírá výuku.
  - `original` (string | volitelné): Přítomno **pouze** u typu `"invalid"`. Obsahuje původní textový řetězec, který se nepodařilo zpracovat.

<details>
<summary>Zobrazit příklady absencí</summary>

**Celý den:**
```json
{
  "teacher": "Jan Novák",
  "teacherCode": "no",
  "type": "wholeDay",
  "hours": null
}
```

**Jedna hodina:**
```json
{
  "teacher": "Jan Novák",
  "teacherCode": "no",
  "type": "single",
  "hours": 1
}
```

**Rozsah hodin (od-do):**
```json
{
  "teacher": "Petr Svoboda",
  "teacherCode": "sv",
  "type": "range",
  "hours": { "from": 2, "to": 4 }
}
```

**Exkurze: (celý den)**
```json
{
  "teacher": "Bc. Jakub Dvořák",
  "teacherCode": "dv",
  "type": "exkurze",
  "hours": null
}
```

**Kompletní zastoupení:**
```json
{
  "teacher": "Ing. Zdeněk Vondra",
  "teacherCode": "vn",
  "type": "zastoupen",
  "hours": null,
  "zastupuje": {
    "teacher": "David Janoušek",
    "teacherCode": "jk"
  }
}
```

**Neplatný záznam:**
```json
{
  "type": "invalid",
  "teacher": null,
  "teacherCode": null,
  "hours": null,
  "original": "Nezpracovatelný text"
}
```
</details>

##### `takesPlace`

String obsahující text aktuálně probíhajících akcí pro daný den (např. akce, exkurze, maturitní zkoušky).

  - Může obsahovat znaky nového řádku `\n` pro oddělení více akcí.
  - Pokud pro daný den žádná akce neprobíhá, vrací prázdný string `""`.

##### `reservedRooms`

Pole o **přesně 10 prvcích**, které reprezentuje rezervace konkrétních místností pro 1. až 10. vyučovací hodinu.

  - `string`: Název rezervované místnosti (např. `"19a"`, `"TV"`).
  - `null`: Pokud pro danou hodinu není evidována žádná rezervace místnosti.

#### Sekce: `status` - Stav a Metadata

Objekt poskytující informace o aktuálnosti dat.

  - `lastUpdated` (string): Čas (ve formátu `HH:MM`), kdy byla data naposledy úspěšně získána a uložena na serveru.
  - `currentUpdateSchedule` (number): Interval v minutách, ve kterém systém periodicky kontroluje nová data (může se měnit v závislosti na denní době - kratší během vyučování, delší v noci).

<details>
<summary>Zobrazit příklad status</summary>

```json
"status": {
  "lastUpdated": "08:30",
  "currentUpdateSchedule": 5
}
```
</details>