# api.tietoa.fi — ohje agenteille ja kehittäjille

Tietoan rajapinta Tietoan omaan master dataan (rekisteri) ja peilin tietoihin. Sama data ja samat
oikeudet REST:llä, GraphQL:llä, MCP:llä (data-mcp.tietoa.fi) ja portaalissa (portaali.tietoa.fi).

## Osoitteet
- REST: `https://api.tietoa.fi/rest/<aineisto>` (PostgREST). Kuvaus: `GET https://api.tietoa.fi/rest/` (OpenAPI 2.0), ihmisille `https://api.tietoa.fi/docs`.
- GraphQL: `POST https://api.tietoa.fi/graphql` body `{"query": "..."}`.
- MCP: `https://data-mcp.tietoa.fi/mcp` (Claude, OAuth) — työkalut `luettele_aineistot`, `kuvaa_aineisto`, `hae`, `hae_rivi`, `ehdota_muutos`, `tallenna`, `laajennuspyynto`.

## Tunnistus
Jokainen datakutsu vaatii `Authorization: Bearer <token>`. Token on Authentikin (auth.tietoa.fi) myöntämä JWT.
Ilman tokenia saa vain OpenAPI-kuvauksen; muu vastaa 401. Väärä rooli vastaa 403.

- **Ihminen** (oma sovellus, skripti): kirjaudu portaaliin tai OIDC-koodivirralla Authentikin providerilla `tietoa-portaali`. Rooli määräytyy Authentik-ryhmistä: johto ja yksikoiden-paallikot → `tietoa_johto`, tietohallinto → `tietoa_tietohallinto`, muut @tietoa.fi → `tietoa_kayttaja`.
- **Sovellus** (Lovable Edge Function, Make, n8n, Python): oma Authentik-provider `api-app_<nimi>`, jonka Tietohallinto luo. Token client credentials -virralla:
  ```
  curl -s https://auth.tietoa.fi/application/o/token/ \
    -d grant_type=client_credentials -d client_id=<id> -d client_secret=<salaisuus> -d scope='openid api'
  ```
  Vastauksen `access_token` kelpaa tunnin. Salaisuus pysyy palvelimella (Edge Functionin secret), ei koskaan selaimessa.
- **Agentti** käyttää MCP:tä: se toimii käyttäjän oikeuksin. Kerro agentin nimi otsakkeella `X-Tietoa-Agentti` (kirjautuu muutoshistoriaan).

Testaa token: `POST /rest/rpc/kuka_olen` palauttaa sähköpostin, roolin ja ryhmät.

## Säännöt
1. Käytä vain tätä rajapintaa. Älä tee omaa kopiota Severan, HubSpotin tai rekisterin datasta.
2. Viittaa avaimella, älä nimellä: organisaatio = `organisaatiot.id` (uuid), henkilö = Severa-guid, projekti = Severa-guid.
3. Mitään ei poisteta: arkistoi `PATCH ... {"arkistoitu": "<aikaleima>"}`. Jokainen muutos kirjautuu (`muutoshistoria`).
4. Jos sinulla ei ole kirjoitusoikeutta, ehdota: `POST /rest/rpc/ehdota_muutos` `{"taulu": "organisaatiot", "rivi_id": "<uuid tai null>", "muutos": {...}, "perustelu": "..."}`. Tietohallinto hyväksyy portaalissa.
5. Puuttuuko tieto tai kenttä? `POST /rest/rpc/laajennuspyynto` `{"mita": "...", "miksi": "...", "ehdotus": "...", "liikennevalo": "vihrea"}`. Älä kierrä rajapintaa.
6. Punaista dataa (henkilötunnus, tilinumero, palkka) ei ole eikä tule.

## Esimerkit (REST)
```
# Organisaatio Y-tunnuksella
GET /rest/organisaatiot?y_tunnus=eq.0102282-6
# Severa-asiakkaan organisaatio (tunnisteet = {"severa": ["<guid>"], ...})
GET /rest/organisaatiot?tunnisteet=cs.{"severa":["<severa-guid>"]}
# Nimihaku, vain tarvittavat kentät, 20 kpl
GET /rest/organisaatiot?nimi=ilike.*skanska*&select=id,nimi,y_tunnus,roolit&limit=20
# Avoimet täsmäytysehdotukset
GET /rest/organisaatio_tunnisteet?tila=eq.ehdotus
# Uusi organisaatio (johto, tietohallinto, sovellukset joilla oikeus)
POST /rest/organisaatiot   {"nimi": "Esimerkki Oy", "y_tunnus": "1234567-8"}   Prefer: return=representation
# Tiedonsiirtojen tila
GET /rest/keraimet?halytys=is.true
```
Suodattimet: `eq, neq, gt, lt, like, ilike, in.(a,b), is.null, cs` · järjestys `order=nimi.asc` · sivutus `limit`, `offset` · upotus viiteavaimia pitkin `select=*,toimittajat(*)`.

## Aineistot (vaihe 1)
| Aineisto | Sisältö | Lukee | Kirjoittaa |
|---|---|---|---|
| `organisaatiot` | golden record: yksi rivi yritystä kohti, roolit ja järjestelmätunnisteet | kaikki | johto, tietohallinto |
| `organisaatio_tunnisteet` | Severa/Procountor/HubSpot/gdpr-tunnisteet, täsmäyttimen ehdotukset | kaikki | johto, tietohallinto |
| `organisaatio_roolit` | asiakas, toimittaja, kumppani… | kaikki | johto, tietohallinto |
| `toimittajat`, `toimittaja_arvioinnit` | toimittajasuhteiden tietoturva (ISO 27001) | johto | tietohallinto |
| `ehdotukset` | muutosehdotukset | omat (tietohallinto kaikki) | `rpc/ehdota_muutos` |
| `laajennuspyynnot` | rajapinnan laajennuspyynnöt | kaikki | `rpc/laajennuspyynto` |
| `keraimet` | tiedonsiirtojen tila ja datan ikä | kaikki | – |
| `muutoshistoria` | kuka muutti mitä | johto | – |

Ajantasainen luettelo kuvauksineen: `GET /rest/` tai `https://api.tietoa.fi/docs`.

Ylläpito: Tietohallinto. Lähdekoodi ja malli: Forgejo `tietoa/tietokartta` (`peili/api_v1.sql`, `masterdata_tavoitetila.yaml` osio `rekisteri`).