> ## 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.

# API:n esittely

> Hallitse QR-koodeja, malleja, analytiikkaa ja raportteja omasta koodistasi.

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

GetQR API on REST-rajapinta niihin toimintoihin, joita teet hallintapaneelissa: QR-koodien luomiseen ja päivittämiseen, niiden kuvien lataamiseen, skannausanalytiikan lukemiseen ja raporttien vientiin. Todenna pyynnöt tilisi API-avaimella ja kutsu versioituja päätepisteitä polun `/api/v1` alla.

## Mitä voit tehdä

> [card] [QR-koodit](https://docs.getqr.com/fi/api/endpoints/qr-codes.md)
>
> Luo, listaa, päivitä, keskeytä, monista, poista ja lataa QR-koodeja.

> [card] [Analytiikka](https://docs.getqr.com/fi/api/endpoints/analytics.md)
>
> Skannausten kokonaismäärät ja erittelyt yhdelle QR-koodille tai koko työtilalle.

> [card] [Raportit](https://docs.getqr.com/fi/api/endpoints/reports.md)
>
> Vie kertaluonteinen raportti tai ajasta toistuvat raporttisähköpostit.

> [card] [Mallit](https://docs.getqr.com/fi/api/endpoints/templates.md)
>
> Tallenna ulkoasuja ja käytä niitä uusissa QR-koodeissa.

> [card] [QR-koodien joukkoluonti](https://docs.getqr.com/fi/api/endpoints/bulk-qr-creations.md)
>
> Luo jopa 100 QR-koodia kerralla JSON-datasta tai CSV-tiedostosta.

> [card] [Tiedostot](https://docs.getqr.com/fi/api/endpoints/files.md)
>
> Lataa QR-koodeillesi PDF-tiedostoja, kuvia, videoita ja logoja.

> [card] [Tilatarkistus](https://docs.getqr.com/fi/api/endpoints/health.md)
>
> Tarkista, että API toimii. API-avainta ei tarvita.

## Oppaat

> [card] [QR-tyypit](https://docs.getqr.com/fi/api/guides/qr-types.md)
>
> Datan muoto kullekin 16 QR-tyypistä.

> [card] [Mukauttaminen](https://docs.getqr.com/fi/api/guides/customization.md)
>
> Pisteiden tyylit, kulmat, värit, kehykset ja logot.

> [card] [Käyttösäännöt](https://docs.getqr.com/fi/api/guides/access-rules.md)
>
> Aikataulut, skannausrajat, salasanat, keskeyttäminen ja poistaminen.

## Perus-URL

Kaikki päätepisteet ovat saman perus-URL:n alla:

```text theme={null}
https://getqr.com/api/v1
```

## Versiointi

API-versio on osa polkua: jokainen päätepiste on polun `/api/v1/` alla.

* Yhteensopivuuden rikkovat muutokset julkaistaan uuden versioetuliitteen alla, kuten `/api/v2/`, ja `/api/v1/` toimii edelleen.
* Lisäävät muutokset, kuten uudet valinnaiset kentät tai uudet päätepisteet, voivat ilmestyä v1:een. Ohita vastauksen kentät, joita koodisi ei tunnista.

## Pika-aloitus

**1. Hanki API-avaimesi**

Luo tai näytä avaimesi tilisi asetuksissa. Katso [Todennus](https://docs.getqr.com/fi/api/authentication.md).

**2. Tarkista, että API on tavoitettavissa**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

Vastaus on `{ "status": "ok", "version": "v1" }`.

**3. Luo ensimmäinen QR-koodisi**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

API vastaa koodilla `201` ja palauttaa uuden QR-koodin, jossa ovat sen `id` ja `shortLink`.

**4. Lataa kuva**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## Pyynnöt ja vastaukset

* **Muoto.** Lähetä pyyntöjen rungot JSON-muodossa otsakkeella `Content-Type: application/json`. Poikkeus on [joukkoluonnin](https://docs.getqr.com/fi/api/endpoints/bulk-qr-creations.md) CSV-lataus, joka käyttää muotoa `multipart/form-data`.
* **Vastaukset.** Vastaukset ovat JSON-muotoisia. Lataukset, kuten QR-kuvat ja joukkoluonnin ZIP-arkistot, palauttavat itse tiedoston.
* **Päivämäärät.** Päivämäärät ovat ISO 8601 -merkkijonoja UTC-ajassa, esimerkiksi `2026-08-01T10:00:00.000Z`.
* **Kyselyparametrit.** Totuusarvoparametrit ottavat merkkijonot `true` tai `false`.
* **Osittaiset päivitykset.** `PATCH`-päätepisteet muuttavat vain lähettämäsi kentät.
* **Salaisuudet.** Vastaukset eivät koskaan sisällä salasanoja tai sisäisiä tunnisteita. Salasanalla suojattu QR-koodi kertoo vain `passwordProtected: true`.
* **Työtila.** Jokainen pyyntö suoritetaan työtilassa, johon API-avaimesi kuuluu. Työtilan tunnusta ei välitetä. Katso [Käyttöoikeudet ja roolit](https://docs.getqr.com/fi/api/authentication.md#käyttöoikeudet-ja-roolit).
* **Virheet.** Epäonnistuneet pyynnöt palauttavat `error`-objektin, jossa on pysyvä `code`. Katso [Virheet](https://docs.getqr.com/fi/api/errors.md).

## Sivutus

Listauspäätepisteet (QR-koodit, mallit ja ajastetut raportit) ottavat kaksi kyselyparametria:

| Parametri | Kuvaus |
| - | - |
| `page` | Palautettava sivu. Oletus `1`. |
| `pageSize` | Tuloksia sivua kohti, enintään `100`. Oletus `100`. |

Ne vastaavat `data`-taulukolla ja `pagination`-objektilla:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Kenttä | Kuvaus |
| - | - |
| `page` | Saamasi sivu. |
| `pageSize` | Saamasi sivun koko. |
| `total` | Tulosten määrä kaikilla sivuilla yhteensä. |
| `hasMore` | `true`, niin kauan kuin seuraava sivu on odottamassa. |

Pyydä seuraava sivu niin kauan kuin `hasMore` on `true`. Yli `100`:n `pageSize` palauttaa virheen [`422`](https://docs.getqr.com/fi/api/errors#validointivirheet).

## Idempotenssi

Verkkovirheen jälkeen et välttämättä tiedä, menikö pyyntö perille. Jotta voit yrittää [QR-koodin luontia](https://docs.getqr.com/fi/api/endpoints/qr-codes.md#luo-qr-koodi) turvallisesti uudelleen, lähetä `Idempotency-Key`-otsake, jonka arvon valitset itse ja joka on yksilöllinen:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* Kun toistat pyynnön samalla avaimella 24 tunnin sisällä, saat alkuperäisen vastauksen, eikä toista QR-koodia luoda.
* Vastausotsake `x-idempotent-replay` on `true` toistetulle vastaukselle ja `false` uudelle.
* Jos ensimmäinen saman avaimen pyyntö on vielä käynnissä, API vastaa `409 conflict`. Yritä uudelleen, kun se on valmis.
* Jos käytät avainta uudelleen eri pyynnön rungolla, vastaus on `422 unprocessable_entity`.
* Ilman otsaketta 30 sekunnin sisällä lähetetty identtinen pyynnön runko käsitellään kaksoiskappaleena.

Joukkoluonnit ottavat sen sijaan pyynnön rungossa kentän `idempotencyKey`. Katso [QR-koodien joukkoluonti](https://docs.getqr.com/fi/api/endpoints/bulk-qr-creations.md).

## Käyttörajoitukset

Kukin API-avain voi lähettää enintään 600 pyyntöä minuutissa. Katso [Käyttörajoitukset](https://docs.getqr.com/fi/api/rate-limits.md).

## Tulossa myöhemmin

Painovalmiit paketit ovat tulossa myöhempään julkaisuun.

## Mitä seuraavaksi

> [card] [Todennus](https://docs.getqr.com/fi/api/authentication.md)

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


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