API-avaimet

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.

TWICE Admin API on alfavaiheessa. Päätepisteet ja skeemat voivat muuttua ilman erillistä ilmoitusta. Kiinnitä API-versio (katso kohta API-versiot alempana) ja tarkista referenssi ennen kuin päivität integraation.

Miten se toimii

API-avaimet luodaan ja hallitaan kohdassa Asetukset → Integraatiot osiossa API access. Jokainen avain kuuluu tilillesi ja toimii sen puolesta.

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.

Kaikki pyynnöt menevät osoitteeseen https://server.twicecommerce.com. Kauppiaalle tarkoitetut päätepisteet ovat polun /v1/admin/ alla — tämä on TWICE Admin API. Lähetä avain X-API-KEY-otsakkeessa jokaisessa pyynnössä. Esimerkiksi katalogin artikkelien listaus:

curl "https://server.twicecommerce.com/v1/admin/catalog" \
  -H "X-API-KEY: {key}"

{
  "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
  }
}

Käyttö

Avaa Asetukset → Integraatiot ja siirry osioon API access.
Luo avain ja kopioi se — koko arvo näytetään vain kerran.
Lisää se integraatioosi X-API-KEY-otsakkeeksi.
Poista avain samasta näkymästä, kun sitä ei enää tarvita. Vahvistusikkuna Poista API-avain pyytää vahvistuksen. Kaikki avaimella tunnistautuvat integraatiot lakkaavat toimimasta välittömästi, eikä poistoa voi perua.

API-versiot

API on versioitu päivämäärän mukaan. Nykyinen versio on 2025-06. Kiinnitä pyyntö versioon lähettämällä se X-API-Version-otsakkeessa:

curl "https://server.twicecommerce.com/v1/admin/catalog" \
  -H "X-API-KEY: {key}" \
  -H "X-API-Version: 2025-06"

Pyyntö, joka ei lähetä versio-otsaketta — tai lähettää version, jota API ei tunne — kohdistuu uusimpaan versioon. Kiinnitä otsake integraatiossa, jonka et halua muuttuvan alta, kun uusi versio julkaistaan. Webhookit kiinnitetään erikseen: jokainen webhook säilyttää sen version, joka oli uusin sen luontihetkellä, joten uusi API-versio ei koskaan muuta jo vastaanottamaasi hyötykuormaa. Katso Webhookit.

Vanhempia polkuja https://server.twicecommerce.com/internal/… vasten kirjoitetut integraatiot toimivat edelleen — nämä osoitteet ohjautuvat polkuun /v1/admin/. Toimivaa skriptiä ei tarvitse kirjoittaa uudelleen. Kirjoita uudet integraatiot polkua /v1/admin/ vasten.

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
`X-RateLimit-Overage`	Asetetaan arvoon `true`, kun kuukausikaton ylittävä pyyntö palvellaan ja laskutetaan ylityksenä sen hylkäämisen sijaan

Kun pyyntö ylittää rajan, API palauttaa 429 Too Many Requests. Odota Retry-After-sekunnit ennen uutta yritystä. Kuukausikaton ylittyminen ei aina palauta arvoa 429. Tileillä, joilla ylitys on sallittu, katon ylittävä pyyntö palvellaan ja laskutetaan ylityksenä; tileillä ilman sitä jokainen katon ylittävä kutsu saa arvon 429. Purskerajan hylkäämä pyyntö ei koskaan tavoita kuukausikattoa, joten sitä ei lasketa mukaan. Pakettikohtaiset kiintiöt löytyvät TWICE Commercen yleiskatsauksen hinnoitteluosiosta.

Aiheeseen liittyvät artikkelit

API-viite

Selaa kaikkia päätepisteitä.

Webhookit

Vastaanota tapahtumia, kun data muuttuu.

Luonti joukkona

Luo useita tietueita yhdellä kutsulla silmukan sijaan.

Integraatioasetukset

Hallitse avaimia ja liitettyjä järjestelmiä.

Tervetuloa TWICE-dokumentaatioon

Liikkuminen TWICEssä

Järjestelmän ymmärtäminen

Miten se toimii

Käyttö

API-versiot

Kutsurajat

Aiheeseen liittyvät artikkelit

API-viite

Webhookit

Luonti joukkona

Integraatioasetukset

​Miten se toimii

​Käyttö

​API-versiot

​Kutsurajat

​Aiheeseen liittyvät artikkelit

API-viite

Webhookit

Luonti joukkona

Integraatioasetukset

Miten se toimii

Käyttö

API-versiot

Kutsurajat

Aiheeseen liittyvät artikkelit