> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Käyttösäännöt

> Ajoita alku ja loppu, rajoita skannausten määrää, vaadi salasana sekä keskeytä, aktivoi uudelleen tai poista QR-koodi.

> [!NOTE]
>
> GetQR API on beetavaiheessa, ja se on käytettävissä valituissa työtiloissa. Yksityiskohdat voivat muuttua ennen yleistä julkaisua.

Hallitse, milloin QR-koodi ohjaa kohteeseensa, kuinka monta kertaa sen voi skannata, kysyykö se salasanaa ja onko se keskeytetty tai poistettu.

## Ennen kuin aloitat

* **Rooli.** Sääntöjen asettaminen, keskeyttäminen, uudelleenaktivointi ja poistaminen vaativat kirjoitusoikeuden työtilan QR-koodeihin. Katso [Todennus](https://docs.getqr.com/fi/api/authentication.md).
* **Tilaus.** Jokainen API-pyyntö, myös nämä, vaatii työtilan omistajalta aktiivisen tilauksen.

## access-objekti

Lähetä `access`-objekti, kun [luot](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#luo-qr-koodi) tai [päivität](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#päivitä-qr-koodi) QR-koodin:

```text theme={null}
POST  /api/v1/qrs
PATCH /api/v1/qrs/{qrId}
```

| Kenttä | Tyyppi | Kuvaus |
| - | - | - |
| `activeAt` | string (ISO 8601) \| null | Ajoitettu alkamisaika. Ennen tätä hetkeä skannaukset näyttävät kohteen sijaan taukosivun. `null` tarkoittaa, että koodi on aktiivinen heti. |
| `pauseAt` | string (ISO 8601) \| null | Ajoitettu päättymisaika. Tästä hetkestä alkaen skannaukset näyttävät taukosivun. `null` tarkoittaa, ettei päättymispäivää ole. |
| `scanLimit` | integer \| null | Skannausten enimmäismäärä QR-koodin koko elinkaaren aikana. Kun raja ylittyy, skannaukset näyttävät taukosivun. `null` tarkoittaa rajoittamatonta. |
| `password` | string \| null | Salasana, joka kävijöiden on annettava ennen uudelleenohjausta. Sen lähettäminen ottaa myös suojauksen käyttöön. |
| `passwordProtected` | boolean | Kysyykö QR-koodi salasanaa. `false` poistaa suojauksen käytöstä mutta säilyttää tallennetun salasanan. `true` ottaa sen taas käyttöön. |

Pois jättämäsi kentät pysyvät ennallaan. Tyhjennä sääntö lähettämällä `null`. Osittainen `access`-objekti ei koskaan nollaa sääntöjä, joita et maininnut.

> [!WARNING]
>
> Käyttösäännöt kuuluvat `access`-objektiin. Kenttien `activeAt`, `pauseAt`, `scanLimit`, `password` tai `passwordProtected` lähettäminen `link`-objektissa palauttaa `422`.

## Ajoita alku ja loppu

`activeAt` ja `pauseAt` ovat toisistaan riippumattomia: aseta kumpi tahansa tai molemmat. Molemmat ottavat ISO 8601 -päivämäärän ja -kellonajan, jossa on `Z` tai UTC-poikkeama.

```bash theme={null}
curl -X PATCH "https://getqr.com/api/v1/qrs/qr_abc123" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {
      "activeAt": "2026-08-01T09:00:00Z",
      "pauseAt": "2026-08-31T23:59:59Z"
    }
  }'
```

Tyhjennä aikataulu lähettämällä `null`. Tällöin QR-koodi on heti aktiivinen, eikä sillä ole päättymispäivää:

```json theme={null}
{
  "access": { "activeAt": null, "pauseAt": null }
}
```

## Skannausraja

Rajoita skannausten kokonaismäärää. Sen jälkeen QR-koodi lakkaa ohjaamasta kohteeseen:

```json theme={null}
{
  "access": { "scanLimit": 500 }
}
```

Koko elinkaaren skannauslaskuri on aina käynnissä riippumatta siitä, onko raja asetettu. Siksi rajan muuttaminen on ennustettavaa:

* **Rajan nostaminen** vapauttaa tarkalleen (uusi raja miinus skannausten kokonaismäärä) lisäskannausta.
* **Rajan laskeminen** nykyisen kokonaismäärän alle estää QR-koodin välittömästi.
* **Rajan asettaminen myöhemmin** laskee mukaan myös skannaukset, jotka tehtiin, kun rajaa ei ollut.

`scanLimit`-arvon on oltava positiivinen kokonaisluku, enintään 2147483647. Lähetä `null`, jos et halua rajaa.

## Salasanasuojaus

Aseta salasana samalla `access`-objektilla. Tallennettu salasana säilyy, kun poistat suojauksen käytöstä, joten voit ottaa sen uudelleen käyttöön lähettämättä salasanaa uudelleen.

**1. Aseta tai vaihda salasana**

Tämä ottaa myös suojauksen käyttöön.

```json theme={null}
{ "access": { "password": "hunter2" } }
```

**2. Poista suojaus käytöstä**

Tallennettu salasana säilyy.

```json theme={null}
{ "access": { "passwordProtected": false } }
```

**3. Ota suojaus uudelleen käyttöön**

Salasanaa ei tarvitse lähettää uudelleen. Tämä toimii vain, jos salasana on jo asetettu. Muuten pyyntö palauttaa `422`.

```json theme={null}
{ "access": { "passwordProtected": true } }
```

* **Luonnissa.** Ota suojaus käyttöön lähettämällä `password`. Pelkällä `passwordProtected`-kentällä ei ole vaikutusta, ennen kuin salasana on olemassa.
* **Salasanan poistaminen.** Lähetä `"password": null`. Myös suojaus poistuu käytöstä.
* **Lukeminen.** Vastaukset eivät koskaan palauta salasanaa, vain kentän `access.passwordProtected`.

## Keskeytä, aktivoi uudelleen ja poista

Keskeyttäminen ja uudelleenaktivointi ovat erillisiä päätepisteitä eivätkä `access`-kenttiä, koska ne tulevat voimaan heti eivätkä aikataulun mukaan.

| Metodi | Polku | Kuvaus |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [Keskeytä QR-koodi nyt](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#keskeytä-qr-koodi). Skannaukset näyttävät taukosivun, kunnes aktivoit koodin uudelleen. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Aktivoi keskeytetty QR-koodi uudelleen](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#aktivoi-qr-koodi-uudelleen). Mahdollinen aikataulu ja skannausraja ovat edelleen voimassa. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Poista QR-koodi](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#poista-qr-koodi) ja sen lyhytlinkki pysyvästi. |

Keskeytys ja aktivointi eivät ota pyynnön runkoa, ja ne palauttavat päivitetyn [QR-koodin](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#qr-koodiobjekti):

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_abc123/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json theme={null}
{
  "id": "qr_abc123",
  "archived": true,
  "…": "…"
}
```

Voit asettaa keskeytystilan myös pyynnöllä `PUT /api/v1/qrs/{qrId}` ja rungolla `{ "archived": true }` tai `PATCH`-pyynnön kentällä `archived`. Katso [Aseta keskeytystila](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#aseta-keskeytystila).

Poistaminen poistaa QR-koodin ja sen lyhytlinkin yhdessä:

```json theme={null}
{ "id": "qr_abc123", "deleted": true }
```

> [!WARNING]
>
> Poistoa ei voi perua. Lyhytlinkki lakkaa ohjaamasta, joten painetut koodit lakkaavat toimimasta. Keskeytä QR-koodi sen sijaan, jos saatat tarvita sitä uudelleen.

## Milloin muutokset tulevat voimaan

* **Seuraava skannaus.** Säännöt tarkistetaan, kun koodi skannataan, joten muutos koskee seuraavasta skannauksesta alkaen eikä takautuvasti.
* **Taukosivu.** QR-koodi, jonka aikataulu, skannausraja tai keskeytys estää, näyttää taukosivun. Skannausta ei ohjata eteenpäin.
* **Salasana.** Kävijät, jotka ovat jo antaneet salasanan, säilyttävät pääsyn, kunnes salasana vaihtuu tai suojaus poistetaan käytöstä ja otetaan uudelleen käyttöön.
* **Kello.** Aikataulut käyttävät palvelimen kelloa UTC-ajassa, eivät kävijän paikallista aikaa.
* **Säännöt yhdistyvät.** QR-koodi ohjaa kohteeseen vain, kun se ei ole keskeytetty, on aikataulunsa sisällä ja on skannausrajansa alla.

## Yleisiä ongelmia

> [accordion] 422, kun asetan säännön link-objektiin
>
> Lähetä sääntö `access`-objektissa, ei `link`-objektissa.

> [accordion] 422, kun otan salasanasuojauksen käyttöön
>
> QR-koodilla ei ole vielä salasanaa. Lähetä `password` kentän `passwordProtected: true` sijaan.

> [accordion] QR-koodi näyttää yhä taukosivun uudelleenaktivoinnin jälkeen
>
> Aikataulu tai skannausraja on yhä voimassa. Tarkista kentät `access.activeAt`, `access.pauseAt` ja `access.scanLimit` [QR-koodista](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#hae-qr-koodi) ja vertaa `scans`-arvoa rajaan.

> [accordion] Haluan linkin vanhenevan
>
> `link.expiresAt` ei ole käytettävissä tässä API:ssa. Käytä sen sijaan kenttää `access.pauseAt`.

## Mitä seuraavaksi

> [card] [QR-koodit](https://docs.getqr.com/fi/api/endpoints/qr-codes.md)

> [card] [QR-koodien data tyypeittäin](https://docs.getqr.com/fi/api/guides/qr-types.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.