# Pätevyyspiste API v1 Rajapinta koulutusten, moduulien, käyttäjien ja pätevyyksien hallintaan. Suunniteltu automaatiolle ja tekoälyagenteille. Perusosoite: `/api/v1` --- ## 1. Tunnistautuminen Jokainen pyyntö tarvitsee API-avaimen otsakkeessa: ``` Authorization: Bearer wtk_xxxxxxxxxxxxxxxxxxxx ``` Vaihtoehtoisesti `X-Api-Key: wtk_...`. **Ympäristö tulee avaimesta.** Et anna etkä voi antaa yritystunnusta missään pyynnössä. Avain on sidottu yhteen ympäristöön, ja kaikki luku ja kirjoitus kohdistuu vain siihen. Avaimen luo yrityksen ylläpitäjä hallintapaneelista: **Asetukset → Integraatiot → Rajapinta (API)**. Rajapinta on oletuksena pois käytöstä, ja se aktivoidaan samasta paikasta. ### Oikeudet Avaimella on yksi tai useampi oikeus: | Oikeus | Mitä sallii | |---|---| | `read` | Kaiken ympäristön sisällön lukeminen. Aina mukana. | | `content:write` | Koulutusten, moduulien, diojen ja kysymysten luonti ja muokkaus. | | `users:write` | Käyttäjien ja ryhmien luonti ja muokkaus. | Jos avaimelta puuttuu tarvittava oikeus, vastaus on **403** ja siinä kerrotaan mikä oikeus puuttuu. Anna agentille vain `read` + `content:write`, ellei sen ole tarkoitus hallita käyttäjätilejä. --- ## 2. Aloita tästä Kutsu ensin: ``` GET /api/v1/me ``` Vastaus kertoo mihin ympäristöön avain osoittaa, mitä oikeuksia sillä on ja paljonko sisältöä ympäristössä on: ```json { "tenant": { "slug": "yritys", "name": "Yritys Oy" }, "key": { "name": "Agentti", "prefix": "wtk_a1b2c3", "scopes": ["read", "content:write"] }, "counts": { "users": 42, "courses": 3, "modules": 18, "groups": 4 }, "docs": "/api/v1/docs" } ``` --- ## 3. Koulutuksen luonti yhdellä kutsulla **Tämä on tavallisin tapa luoda koulutus.** Koko rakenne — koulutus, moduulit, diat ja tietovisan kysymykset — syntyy yhdestä pyynnöstä. ``` POST /api/v1/courses/full ``` Runko: ```json { "title": "Tietosuojan perusteet", "description": "Henkilötietojen käsittely arjessa.", "published": false, "completeWithinWeeks": 4, "modules": [ { "title": "Mitä henkilötieto on", "icon": "ti-shield-lock", "passThreshold": 80, "slides": [ { "heading": "Henkilötieto arjessa", "content": "

Henkilötieto on mikä tahansa tieto, josta henkilö voidaan tunnistaa.

" }, { "heading": "Milloin tietoa saa käsitellä", "content": "

Käsittelylle tarvitaan aina peruste.

" } ], "questions": [ { "question": "Onko työsähköpostiosoite henkilötietoa?", "type": "boolean", "correctIndex": 0, "feedbackOk": "Kyllä — osoitteesta voi tunnistaa henkilön." }, { "question": "Mitkä näistä ovat henkilötietoa?", "type": "multi", "options": ["Nimi", "Y-tunnus", "Kotiosoite", "Sään lämpötila"], "correctIndexes": [0, 2], "feedbackOk": "Nimi ja kotiosoite tunnistavat henkilön." } ] } ] } ``` ### Säännöt - `title` on pakollinen. Jokainen moduuli tarvitsee `title`-kentän ja **vähintään yhden dian**. - Kysymykset ovat vapaaehtoisia. Moduuli ilman kysymyksiä on pelkkää luettavaa. - Enintään 50 moduulia yhdessä pyynnössä. - `minScore` on **pistemäärä, ei prosentti**: se on todistukseen vaadittu yhteispistemäärä, ja koulutuksen enimmäispisteet ovat sen tietovisojen kysymysten määrä (kysymyksettömästä moduulista tulee 1 piste). `0` tarkoittaa, ettei pistevaatimusta ole. - **Koulutus luodaan julkaisemattomana**, ellei annat `"published": true`. Julkaisematon koulutus ei näy henkilöstölle. Tämä on tarkoituksellista: automaatin tekemä koulutus kannattaa katsoa läpi ennen jakelua. - **Koko pyyntö validoidaan ennen kirjoittamista.** Jos jokin kohta on kelvoton, mitään ei luoda ja virheviesti osoittaa tarkan kohdan, esim. `"modules[1].questions[0]: \"correctIndex\" on kokonaisluku väliltä 0–3"`. Vastaus (201) sisältää luodun koulutuksen tunnisteineen sekä kentän `next`, joka kertoo seuraavan järkevän toimenpiteen. --- ## 4. Diojen sisältö Kenttä `content` on HTML:ää. Käytä yksinkertaisia elementtejä: `

` `