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

# API-avaimet

> Tunnista ulkoiset järjestelmät TWICE Commercen API:lle API-avaimilla.

API-avaimilla ulkoiset järjestelmät tunnistautuvat TWICE Commercen API:lle — samalle API:lle, jolla hallinta toimii. Käytä niitä integraatioissa, skripteissä ja headless-verkkokaupoissa.

## Miten se toimii

API-avaimet luodaan ja hallitaan kohdassa [Asetukset → Integraatiot](/docs/fi/settings/integrations) osiossa **API access**. Jokainen avain kuuluu tilillesi ja toimii sen puolesta.

<Warning>
  API-avaimia ei ole rajattu. Jokainen avain saa **omistajatason oikeudet**: se voi kutsua kaikkia tilisi reittejä, mukaan lukien tilausten, asiakkaiden, varaston ja asetusten luku ja kirjoitus. Avainkohtaisia oikeusrajauksia tai rooleja ei ole. Käsittele avainta kuin omistajan salasanaa — säilytä se salaisuutena, älä koskaan tallenna sitä versionhallintaan ja vaihda se välittömästi, jos se vuotaa.
</Warning>

Kaikki pyynnöt menevät osoitteeseen `https://server.twicecommerce.com`. Lähetä avain `X-API-KEY`-otsakkeessa jokaisessa pyynnössä. Esimerkiksi katalogin artikkelien listaus:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://server.twicecommerce.com/internal/catalog" \
    -H "X-API-KEY: {key}"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "id": "b4f0a2ce-58d1-4f6e-9a1d-7c2e0f3a9b41",
        "name": "Trail Bike",
        "internalName": "trail-bike-2026",
        "status": "active",
        "taxonomyCategoryId": null,
        "createdAt": "2026-07-14T09:32:11.000Z"
      }
    ],
    "pagination": {
      "page": 0,
      "pageSize": 50,
      "total": 1,
      "totalPages": 1
    }
  }
  ```
</CodeGroup>

## Käyttö

1. Avaa [Asetukset → Integraatiot](/docs/fi/settings/integrations) ja siirry osioon **API access**.
2. Luo avain ja kopioi se — koko arvo näytetään vain kerran.
3. Lisää se integraatioosi `X-API-KEY`-otsakkeeksi.
4. Kumoa avain samasta näkymästä, kun sitä ei enää tarvita.

## Kutsurajat

API rajoittaa pyyntöjä kolmella tasolla:

* **IP-kohtainen** — suojaus ennen tunnistautumista. Jokaisella asiakas-IP:llä on minuuttikohtainen pyyntöbudjetti. Pyynnöt, joissa user agent puuttuu tai vaikuttaa botilta, kuluttavat budjettia enemmän kutsua kohden.
* **Tilikohtainen** — kaikki tilisi tunnistautunut liikenne (hallinta ja API-avaimet yhteensä) jakaa saman minuuttikohtaisen rajan, joka skaalautuu pakettisi mukaan.
* **API-avainkohtainen** — jokaisella avaimella on jatkuva pyyntömäärä sekunnissa, lyhytaikainen purskevara ja kuukausittainen pyyntökatto. Kaikki kolme skaalautuvat pakettisi mukaan; kuukausikatto on API-kutsukiintiö, joka on yhteinen kaikille sijainneillesi.

Vastaukset sisältävät kutsurajaotsakkeet:

| Otsake                  | Merkitys                                                                                                  |
| :---------------------- | :-------------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Nykyisen rajoitusikkunan pyyntöbudjetti                                                                   |
| `X-RateLimit-Remaining` | Ikkunassa jäljellä olevat pyynnöt                                                                         |
| `X-RateLimit-Reset`     | Unix-aikaleima (sekunteina), jolloin ikkuna nollautuu                                                     |
| `Retry-After`           | Sekunnit, jotka on odotettava ennen uutta yritystä — lähetetään vastauksen `429 Too Many Requests` mukana |
| `X-RateLimit-Warning`   | Asetetaan, kun avain lähestyy kuukausikattoaan                                                            |

Kun pyyntö ylittää rajan, API palauttaa `429 Too Many Requests`. Odota `Retry-After`-sekunnit ennen uutta yritystä. Pakettikohtaiset kiintiöt löytyvät [TWICE Commercen yleiskatsauksen](/docs/fi/twice-commerce-overview) hinnoitteluosiosta.

## Aiheeseen liittyvät

<CardGroup cols={2}>
  <Card title="API-viite" icon="code" href="https://server.twicecommerce.com/api/internal">
    Selaa kaikkia päätepisteitä.
  </Card>

  <Card title="Webhookit" icon="webhook" href="/docs/fi/concepts/integrations/webhooks">
    Vastaanota tapahtumia, kun data muuttuu.
  </Card>

  <Card title="Integraatioasetukset" icon="plug" href="/docs/fi/settings/integrations">
    Hallitse avaimia ja liitettyjä järjestelmiä.
  </Card>
</CardGroup>