Rajapinta (API) ja API-avaimet

VAREK:n julkinen REST-rajapinta mahdollistaa vika- ja reklamaatiotietojen lukemisen suoraan omiin järjestelmiisi tai kumppaniohjelmistoihin. Rajapinta on tarkoitettu hallituksen ylläpitäjille ja teknikoille, jotka haluavat automatisoida tiedonsiirtoa tai rakentaa omia raporttinäkymiä.

:::note Vain hallituksen ylläpitäjälle. API-avainten hallinta näkyy vain taloyhtiön hallituksen ylläpitäjälle. Muut roolit eivät näe tätä osiota Asetuksissa. :::

Mikä on julkinen rajapinta?

Rajapinta (API, Application Programming Interface) on tapa hakea tietoja VAREK:sta ohjelmallisesti — ilman kirjautumista käyttöliittymään. Avainten avulla voit esimerkiksi:

• hakea avoimet vikailmoitukset kiinteistönhallintajärjestelmääsi,
• seurata reklamaatioiden tilaa ulkoisessa raportointityökalussa,
• automatisoida tietojen vientiä tai koontinäyttöjä.

API-avaimen luominen

1. Kirjaudu sisään hallituksen ylläpitäjänä.
2. Mene Asetukset → API-avaimet.
3. Valitse Luo uusi avain.
4. Anna avaimelle kuvaava nimi (esim. “Kiinteistöjärjestelmä 2026”).
5. Valitse tarvittavat käyttöoikeudet (scopet):
   • defects:read — vikailmoitusten lukuoikeus
   • claims:read — reklamaatioiden lukuoikeus
   • documents:read — dokumenttien luku- ja latausoikeus
   • bookings:read — tilojen ja varausten lukuoikeus
   • inspections:read — tarkastusten ja havaintojen lukuoikeus
   • maintenance:read — kunnossapitosuunnitelmien (KPTS) lukuoikeus
   • announcements:read — tiedotekanavien ja tiedotteiden lukuoikeus
6. Vahvista luonti.

:::caution Avain näytetään vain kerran. Kopioi avain välittömästi — se alkaa merkeillä vrk_live_…. Avainta ei voi nähdä uudelleen. Jos avain katoaa, luo uusi ja poista vanha. :::

Tunnistautuminen (Bearer-token)

Kaikki rajapintakutsut edellyttävät Authorization-otsikkoa:

Authorization: Bearer vrk_live_…

Avain liitetään jokaisen HTTP-pyynnön otsikkoon. Älä jaa avainta tai tallenna sitä versionhallintaan.

:::note Rajapinta edellyttää tilauspakettia, johon API-käyttö sisältyy. API-avaimia voi luoda vain, kun taloyhtiön paketti sisältää rajapintamoduulin. Jos paketti vaihtuu suppeampaan (esim. VAREK Reklamaatio -moduulipakettiin), olemassa olevat avaimet lakkaavat toimimasta heti (vastaus 403 feature_not_in_plan) ja webhook-toimitukset pysähtyvät. Avaimia ei poisteta — ne alkavat toimia uudelleen, kun paketti taas sisältää API-käytön. :::

Perus-URL ja versiointi

https://api.varek.fi/v1

Kaikki päätepisteet alkavat tällä polulla. Versio v1 on nykyinen vakaa versio.

Esimerkkikysely

Hae taloyhtiön vikailmoitukset curl-komennolla:

curl -s \
  -H "Authorization: Bearer vrk_live_AVAIMESI" \
  "https://api.varek.fi/v1/defects?limit=10"

Vastaus on JSON-muodossa ja sisältää kentät data (taulukko) sekä sivutusmetatiedot.

Saatavilla olevat päätepisteet

Päätepiste	Metodi	Scope	Kuvaus
/v1/defects	GET	defects:read	Hae vikailmoitukset (sivutettu)
/v1/defects/{id}	GET	defects:read	Hae yksittäinen vikailmoitus
/v1/claims	GET	claims:read	Hae reklamaatiot (sivutettu)
/v1/claims/{id}	GET	claims:read	Hae yksittäinen reklamaatio
/v1/documents	GET	documents:read	Hae dokumenttien metatiedot (sivutettu)
/v1/documents/{id}	GET	documents:read	Hae yksittäisen dokumentin metatiedot
/v1/documents/{id}/download	GET	documents:read	Hae lyhytikäinen (120 s) allekirjoitettu latauslinkki
/v1/facilities	GET	bookings:read	Hae varattavat tilat (saunat, pesutuvat, kerhohuoneet…)
/v1/facilities/{id}	GET	bookings:read	Hae yksittäinen tila
/v1/bookings	GET	bookings:read	Hae tilavaraukset (sivutettu, suodattimet)
/v1/bookings/{id}	GET	bookings:read	Hae yksittäinen varaus
/v1/inspections	GET	inspections:read	Hae tarkastukset (sivutettu, suodattimet)
/v1/inspections/{id}	GET	inspections:read	Hae yksittäinen tarkastus
/v1/inspections/{id}/findings	GET	inspections:read	Hae tarkastuksen havainnot
/v1/maintenance-plans	GET	maintenance:read	Hae kunnossapitosuunnitelmat eli KPTS:t (sivutettu, suodattimet)
/v1/maintenance-plans/{id}	GET	maintenance:read	Hae yksittäinen kunnossapitosuunnitelma
/v1/maintenance-plans/{id}/items	GET	maintenance:read	Hae suunnitelman korjaustoimenpiteet
/v1/announcement-channels	GET	announcements:read	Hae tiedotekanavat (sivutettu)
/v1/announcement-channels/{id}	GET	announcements:read	Hae yksittäinen tiedotekanava
/v1/announcements	GET	announcements:read	Hae tiedotteet (sivutettu, suodattimet)
/v1/announcements/{id}	GET	announcements:read	Hae yksittäinen tiedote
/v1	GET	—	Rajapintameta (version, links)
/v1/openapi.json	GET	—	OpenAPI 3.1 -määrittely

Dokumenttien rajaukset: rajapinta palauttaa vain dokumenttien metatiedot ja erillisen latauslinkin — ei koskaan suoria tallennuspolkuja. Hallituksen sisäiset (hallitus_only) ja huoneistokohtaiset (apartment_scoped) dokumentit eivät näy rajapinnassa lainkaan. Tiedosto, jonka haittaohjelmatarkistus on kesken tai joka on karanteenissa, palauttaa latauslinkin sijaan virheen file_not_cleared (403).

Varausten rajaukset: varaukset palautetaan huoneistokohtaisina, ei henkilökohtaisina — varaajan henkilöllisyys, vierasvaraajan yhteystiedot ja varausten hallintatunnisteet eivät koskaan näy rajapinnassa. /v1/bookings tukee suodattimia:

• ?facility_id=<uuid> — vain tietyn tilan varaukset
• ?from=…&to=… — varaukset, jotka osuvat aikaväliin [from, to) (ISO 8601 -aikaleimat; puuttuva raja on avoin)
• ?status=confirmed tai ?status=cancelled — ilman suodatinta myös perutut varaukset palautetaan (kalenterisynkronointia varten)

Virheellinen suodatinarvo palauttaa 400-virheen koodilla invalid_parameter.

Tarkastusten rajaukset: tarkastukset (vuositarkastukset, 10-vuotistarkastukset, kuntokartoitukset ja omat tarkastukset) palautetaan ilman henkilötietoja — tarkastajan nimi tai käyttäjätunniste ei koskaan näy rajapinnassa. Havaintojen valokuvista palautetaan vain lukumäärä (photo_count), ei tiedostopolkuja tai latauslinkkejä. Havainnon defect_id kertoo, mihin vikailmoitukseen havainto on viety (haettavissa /v1/defects/{id}-päätepisteestä). /v1/inspections tukee suodattimia:

• ?state=completed tai ?state=in_progress — valmiit tai kesken olevat
• ?scope=apartment tai ?scope=common_area — huoneisto- tai yleisten tilojen tarkastukset
• ?from=…&to=… — tarkastukset, jotka on aloitettu aikavälillä [from, to) (ISO 8601 -aikaleimat; puuttuva raja on avoin)

Havaintolistaa voi suodattaa tilalla: ?status=ok|fail|na|pending. Virheellinen suodatinarvo palauttaa 400-virheen koodilla invalid_parameter.

Kunnossapitosuunnitelmien (KPTS) rajaukset: suunnitelmat palautetaan ilman henkilötietoja — laatijan tai hyväksyjän käyttäjätunniste ei koskaan näy rajapinnassa (finalized_at-aikaleima kertoo lukitushetken). Taloyhtiöllä on kerrallaan enintään yksi active-tilainen suunnitelma; finalized-tilaiset ovat yhtiökokouksille lukittua historiaa. Toimenpiderivit sisältävät komponentin, suunnitellun toteutusvuoden ja hallituksen kustannusarvion (estimated_cost). Tarkastuksesta viety toimenpide kantaa source_finding_id -kentän, joka linkittää takaisin /v1/inspections/{id}/findings-havaintoon. /v1/maintenance-plans tukee suodattimia:

• ?status=active tai ?status=finalized
• ?agm_year=2026 — tietyn yhtiökokousvuoden suunnitelma

Toimenpidelistaa voi suodattaa: ?status=planned|budgeted|in_progress|done|deferred, ?component=roof|facade|plumbing|… ja ?planned_year=2027. Virheellinen suodatinarvo palauttaa 400-virheen koodilla invalid_parameter.

Tiedotekanavien rajaukset: rajapinta näyttää vain tiedotekanavat — viralliset kanavat, joihin vain ylläpitäjät voivat kirjoittaa. Asukaschatit, yksityiset ja huoneistokohtaiset kanavat eivät näy rajapinnassa lainkaan, eivätkä hallituksen sähköpostit tai vieraskanavien istunnot ole rajapinnan piirissä. Tiedotteista palautetaan vain kanavan päätason viestit, jotka on kirjoitettu kanavan tiedotetilan aikana — asukkaiden ketjuvastaukset, poistetut viestit, järjestelmäviestit ja tiedotetilaa edeltävä keskusteluhistoria eivät koskaan näy — ja tiedotteet ovat henkilötiedottomia: kirjoittajan nimi tai käyttäjätunniste ei näy rajapinnassa. Tiedotteen attached_document_ids-kenttä linkittää liitteet /v1/documents/{id}-päätepisteeseen (vaatii documents:read-scopen; dokumentin oma näkyvyysmalli pätee). /v1/announcements tukee suodattimia:

• ?channel_id=<uuid> — vain tietyn tiedotekanavan tiedotteet
• ?pinned=true tai ?pinned=false — kiinnitetyt tai kiinnittämättömät
• ?from=…&to=… — tiedotteet, jotka on luotu aikavälillä [from, to) (ISO 8601 -aikaleimat; puuttuva raja on avoin)

Kanavalistaa voi suodattaa: ?archived=true|false. Virheellinen suodatinarvo palauttaa 400-virheen koodilla invalid_parameter.

Sivutus

Listoissa käytetään kyselyparametreja:

• ?limit=N — rivimäärä vastauksessa (1–100, oletus 50)
• ?offset=N — ohitettavien rivien määrä (sivutuksen siirtymä)

Esimerkki: GET /v1/defects?limit=50&offset=100

Nopeusrajoitus

Avainkohtainen raja on noin 120 pyyntöä minuutissa. Rajan ylittyessä palvelu palauttaa HTTP 429 Too Many Requests.

Päivittäinen kutsuraja (valinnainen)

Jokaiselle avaimelle voi lisäksi asettaa päivittäisen kutsurajan (Asetukset → API-avaimet → avainrivin Muokkaa). Raja on avainkohtainen kutsujen enimmäismäärä vuorokaudessa; tyhjä kenttä tarkoittaa, ettei rajaa ole.

• Vuorokausi vaihtuu keskiyöllä UTC-aikaa (UTC-vuorokausi) — Suomen aikaan kello 02 tai 03 vuodenajasta riippuen.
• Rajan ylittävät kutsut saavat vastauksen 429 virhekoodilla daily_call_cap_exceeded. Retry-After-otsikko kertoo sekunteina, milloin laskuri nollautuu.
• Avainlistan Käyttö tänään / raja -sarake näyttää kuluvan UTC-vuorokauden toteutuneen käytön. Laskuriin lasketaan myös rajan ylityksen jälkeen tehdyt (hylätyt) kutsuyritykset, joten lukema voi ylittää rajan.

Virheviestit (RFC 9457)

Virheet palautetaan application/problem+json-tyypissä RFC 9457 -standardin mukaisesti:

{
  "type": "about:blank",
  "title": "invalid_api_key",
  "status": 401,
  "detail": "Missing or malformed API key."
}

Koneluettava virhekoodi on title-kentässä (esim. invalid_api_key, insufficient_scope, rate_limited, daily_call_cap_exceeded, not_found); type on aina about:blank. Tunnista virheet title-kentän perusteella, älä type-kentän.

Yleisimmät HTTP-statuskoodit:

Koodi	Merkitys
200	Onnistui
400	Virheellinen pyyntö (esim. väärä parametri)
401	Tunnistautuminen puuttuu tai avain on virheellinen
403	Avaimella ei ole tarvittavaa scopea
429	Nopeusraja tai päivittäinen kutsuraja ylitetty
500	Palvelinvirhe

Interaktiivinen API-dokumentaatio

Kokeile rajapintaa selaimessa VAREK:n interaktiivisessa Scalar-referenssisivulla:

varek.fi/docs/api

Sivulta löydät myös raakamuotoisen OpenAPI 3.1 -määrittelyn:

https://api.varek.fi/v1/openapi.json

TypeScript-asiakaskirjasto (SDK)

Jos rakennat integraatiota TypeScriptillä tai JavaScriptillä, voit käyttää virallista tyypitettyä asiakaskirjastoa @varek/sdk sen sijaan, että kutsuisit rajapintaa käsin. Se hoitaa tunnistautumisen, sivutuksen ja virheiden käsittelyn puolestasi, ja tyypit on generoitu samasta OpenAPI-määrittelystä, joten ne pysyvät ajan tasalla rajapinnan kanssa.

npm install @varek/sdk

import { createVarekClient } from "@varek/sdk";

const varek = createVarekClient({ apiKey: "vrk_live_..." });

const { data } = await varek.listDefects({ limit: 50 });
const claim = await varek.getClaim("…");

Valinnaiset asetukset (SDK 0.2.1+):

• timeoutMs — pyyntökohtainen aikakatkaisu millisekunteina. Ilman sitä pyyntö odottaa selaimen/ajoympäristön oletusrajaan asti.
• baseUrl — oletuksena https://api.varek.fi. Osoitteen on oltava https:// — kirjasto hylkää salaamattoman osoitteen, ellei kehityskäyttöön tarkoitettua allowInsecure: true -lippua ole asetettu (älä käytä sitä tuotannossa).

const varek = createVarekClient({
  apiKey: "vrk_live_...",
  timeoutMs: 15_000,
});

Kirjasto löytyy npm:stä: npmjs.com/package/@varek/sdk.

Katso myös

• Asetukset ja tilaus
• Käyttäjät ja roolit
• Tilaus ja laskutus