Luonti joukkona

Lähetä yksi joukkokutsu silmukan sijaan. Admin API luo varastoartikkelit, SKU:t, asiakkaat ja tilausrivit taulukosta, ja yksi kutsu kuluttaa API-avaimen kiintiöstä yhden pyynnön riippumatta siitä, montako tietuetta se sisältää. Päätä ennen luontia, montako tietuetta tili tarvitsee. Yksilöllinen seuranta on mallinnuspäätös, ei määräkysymys.

Päätä ensin tietueiden muoto

Kysy, tarvitseeko jokainen kappale oman historiansa.

Jokainen kappale tarvitsee	Luo	Lopputulos
Oman koodin, kunnon, huoltohistorian sekä tulot ja kulut	Yhden yksilöllisesti seurattavan varastoartikkelin kappaletta kohden	`N` tietuetta, joilla kullakin on oma aikajanansa
Ei mitään omaa, koska mikä tahansa kappale kelpaa	Yhden varastoartikkelin, joka kantaa määrän	Yhden tietueen, joka kattaa `N` kappaletta

Neljänkymmenen pyörän vuokrakalusto tarvitsee 40 tietuetta: jokaisella rungolla on sarjanumero, oma huoltonsa ja omat korjauskulunsa. Tuhannen samanlaisen t-paidan jälleenmyyntilistaus tarvitsee yhden tietueen, jonka määrä on 1 000. Kappalekohtaiset tietueet keskenään vaihdettavasta varastosta antavat tilille 1 000 riviä selattavaksi siinä, missä yksi riittäisi, ja hajauttavat saatavuuslaskennan tietueisiin, joita ei olisi tarvinnut erotella. Valitse tapa luontipyynnön trackIndividually-kentällä (hallinnassa Seuraa yksilöllisesti). Katso Varaston seuranta, mitä kumpikin tapa raportoi ja mistä se luopuu.

Miten se toimii

Neljä päätepistettä ottaa vastaan taulukon:

Päätepiste	Luo	Yksi taulukon alkio on
`POST /v1/admin/articles/create-many`	Varastoartikkeleita	Yksi varastoartikkeli
`POST /v1/admin/skus/many`	SKU:ita	Yksi SKU
`POST /v1/admin/customers/many`	Asiakkaita	Yksi asiakas, tunnistettuna sähköpostista
`POST /v1/admin/orders/{orderId}/lineItems/create-many`	Rivejä yhdelle olemassa olevalle tilaukselle	Yksi rivi

Jokainen alkio luo täsmälleen yhden tietueen. Päätepisteessä articles/create-many quantity asettaa kyseisen yhden tietueen kapasiteetin: se ei koskaan monista alkioita, ja trackIndividually luetaan vain yksittäisessä luonnissa. Varastoartikkeleita voi siis luoda kahdella tavalla, jotka vastaavat eri kysymyksiin:

Sama artikkeli, monta yksilöllisesti seurattavaa kappaletta. Kutsu POST /v1/admin/articles kerran ja anna quantity. Jokaisesta kappaleesta tulee oma tietueensa.
Toisistaan poikkeavat kappaleet nimen, SKU:n, toimipisteen tai attribuuttien osalta. Kutsu POST /v1/admin/articles/create-many ja anna yksi alkio tietuetta kohden.

Käyttö

Varastoartikkelit

Luo 40 yksilöllisesti seurattavaa pyörää yhdellä kutsulla. codes antaa ensimmäisen koodin ensimmäiselle kappaleelle, toisen toiselle ja muodostaa koodin niille kappaleille, joille et anna omaa.

curl -X POST https://server.twicecommerce.com/v1/admin/articles \
  -H "X-API-KEY: {key}" \
  -H "Content-Type: application/json" \
  -d '{
    "article": {
      "name": "Maastopyörä 29\"",
      "serviceLocationId": "9f1c2d84-4c1e-4a0b-9b62-3a7e5c118d20",
      "taxonomyCategoryId": null,
      "quantity": 40,
      "trackIndividually": true,
      "codes": ["BIKE-001", "BIKE-002", "BIKE-003"]
    }
  }'

[
  {
    "id": "3c8a5f21-0e9d-4a17-9c33-6b2f0d51a884",
    "name": "Maastopyörä 29\"",
    "status": "active",
    "codes": ["BIKE-001"],
    "quantity": { "total": 1 }
  },
  {
    "id": "b71d0c46-2f83-4d59-8a05-9e4c7a1b3f62",
    "name": "Maastopyörä 29\"",
    "status": "active",
    "codes": ["BIKE-002"],
    "quantity": { "total": 1 }
  }
]

Keskenään vaihdettavalle varastolle lähetä trackIndividually: false ja sama quantity. Vastauksena tulee yksi tietue, jonka quantity.total on 40. Käytä create-many-päätepistettä, kun alkiot poikkeavat toisistaan:

curl -X POST https://server.twicecommerce.com/v1/admin/articles/create-many \
  -H "X-API-KEY: {key}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Kokoustilan tuoli",
      "serviceLocationId": "9f1c2d84-4c1e-4a0b-9b62-3a7e5c118d20",
      "taxonomyCategoryId": null,
      "quantity": 120,
      "codes": ["CHAIR-POOL-A"]
    },
    {
      "name": "Villakangastakki, koko M",
      "serviceLocationId": "5d2b6e07-1a44-4f8c-bb90-2c6d3e7f4a15",
      "taxonomyCategoryId": null,
      "codes": ["RESALE-2026-0184"]
    }
  ]'

[
  {
    "id": "e0a4b913-77c6-42de-9f1a-08b5c2d63417",
    "name": "Kokoustilan tuoli",
    "status": "active",
    "codes": ["CHAIR-POOL-A"],
    "quantity": { "total": 120 }
  },
  {
    "id": "1f6c8d25-93ab-4e07-8c14-5a9b0e3d7268",
    "name": "Villakangastakki, koko M",
    "status": "active",
    "codes": ["RESALE-2026-0184"],
    "quantity": { "total": 1 }
  }
]

SKU:t

POST /v1/admin/skus/many luo yhden SKU:n alkiota kohden ja palauttaa kunkin id:n, nimen ja koodin. Jos jätät code-kentän pois, TWICE muodostaa koodin nimestä ja lisää numeropäätteen, kunnes koodi on tilillä uniikki. Jos annat koodin, joka on jo käytössä, kutsu epäonnistuu virheeseen 400, joka nimeää koodin. Silloin mitään ei luoda: koko taulukko kirjoitetaan yhtenä transaktiona.

curl -X POST https://server.twicecommerce.com/v1/admin/skus/many \
  -H "X-API-KEY: {key}" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "Maastopyörä 29\"", "code": "TRA-BI-29" },
    { "name": "Studio A" }
  ]'

[
  { "id": "a2d47e19-6c30-4b85-9f27-0e1a8d5c3b46", "name": "Maastopyörä 29\"", "code": "TRA-BI-29" },
  { "id": "7b93f0c5-8d21-4a6e-b013-4c5f2e9a7d81", "name": "Studio A", "code": "ST-A" }
]

Asiakkaat

POST /v1/admin/customers/many palauttaa yhden id:n alkiota kohden. Alkio, jonka sähköposti on jo tilillä, päivittää kyseisen asiakkaan sen sijaan että loisi toisen, ja pois jättämäsi kentät säilyttävät tallennetut arvonsa. Ilman sähköpostia lähetetyt alkiot lisätään aina, joten toistettu tuonti ilman sähköposteja kerryttää kaksoiskappaleita.

curl -X POST https://server.twicecommerce.com/v1/admin/customers/many \
  -H "X-API-KEY: {key}" \
  -H "Content-Type: application/json" \
  -d '[
    { "firstName": "Aino", "lastName": "Virtanen", "email": "aino@example.com", "marketingConsent": true },
    { "firstName": "Marek", "lastName": "Novak", "email": "marek@example.com", "marketingConsent": false }
  ]'

{
  "ids": [
    "c41e7b26-9a58-4d03-8f16-2b7d0c5e9a34",
    "8d2f5a70-3c19-4be8-a742-6f0b1d8c37e5"
  ]
}

Tilausrivit

POST /v1/admin/orders/{orderId}/lineItems/create-many lisää useita rivejä yhdelle olemassa olevalle tilaukselle. Jokaisella rivillä on oma quantity, joten samanlaiset rivit eivät tarvitse omaa alkiota kukin. Hinnat lasketaan palvelimella katalogikohteen ja hinnoittelurivin perusteella.

curl -X POST https://server.twicecommerce.com/v1/admin/orders/6e0f3b74-52a8-4c19-9d75-8b1e4a2c6f03/lineItems/create-many \
  -H "X-API-KEY: {key}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "catalogItemId": "d5b81f39-7a02-4c68-9e14-3f7a5c0b28d6",
      "pricingRowId": "2a7c6e40-8b13-49f5-a0d2-7c9e5b1f3a48",
      "purchaseType": "booking",
      "quantity": 12,
      "startDate": "2026-10-02T08:00:00.000Z",
      "endDate": "2026-10-02T16:00:00.000Z"
    }
  ]'

[
  {
    "id": "9c3a7d18-4b65-42f0-8e29-1d6b0a5c7e93",
    "catalogItemId": "d5b81f39-7a02-4c68-9e14-3f7a5c0b28d6",
    "purchaseType": "booking",
    "quantity": 12,
    "startDate": "2026-10-02T08:00:00.000Z",
    "endDate": "2026-10-02T16:00:00.000Z"
  }
]

Tarkista koodit ja sähköpostit ennen lähetystä

Aja tarkistuspäätepiste koko listalle ensin ja selvitä päällekkäisyydet etukäteen. Kukin palauttaa vain ne alkiot, jotka epäonnistuisivat, joten tyhjä invalid-taulukko tarkoittaa, että erä voidaan lähettää.

Aja tämä	Se palauttaa
`POST /v1/admin/articles/validate-codes` kentällä `{ "codes": [...] }`	Jo käytössä olevat varastoartikkelien koodit, kukin arvolla `reason: "existing"`
`POST /v1/admin/skus/validate-codes` kentällä `{ "codes": [...] }`	Jo käytössä olevat SKU-koodit
`POST /v1/admin/customers/validate-emails` kentällä `{ "emails": [...] }`	Sähköpostit, jotka ovat jo asiakkaalla ja joihin tuonti yhdistäisi tiedot

Erän koko ja kutsurajat

Yksi kutsu on yksi pyyntö. Silmukka, jossa on 1 000 yksittäistä luontia, kuluttaa avaimen sekuntikohtaisesta rajasta ja kuukausikatosta 1 000 pyyntöä; sama tuonti joukkokutsuina kuluttaa muutaman. Katso API-avaimet ja sen kutsurajoja käsittelevä osio, jossa kuvataan kolme tasoa ja vastausten otsakkeet, jotka kertovat jäljellä olevan budjetin. API ei määrittele taulukon pituudelle eikä quantity-kentälle ylärajaa, joten mikään ei hylkää pyyntöä luoda kymmenen miljoonaa tietuetta. Pidä muutamaa sataa tai enintään noin tuhatta alkiota kutsua kohden ohjeena, ei rajana, ja jaa suurempi tuonti useaan kutsuun. Jakaminen tekee myös virheestä halvan korjata. SKU:t ja asiakkaat kirjoitetaan yhtenä transaktiona, joten hylätty alkio ei jätä jälkeensä mitään. Hyvin suuri varastoartikkelitaulukko kirjoitetaan osissa, joten taulukon alkupään alkiot voivat olla olemassa, vaikka myöhempi alkio epäonnistuu. Lähetä eriä, jotka voit yrittää uudelleen, ja kirjaa ylös, mitkä niistä palauttivat 200.

Kaikki tuonnit eivät tarvitse API:a. Hallinnassa varastoartikkelit ja asiakkaat voi tuoda CSV-tiedostosta, mikä on kertaluonteisessa siirrossa yleensä nopeampi reitti. Katso Varaston tuonti CSV-tiedostosta ja Asiakkaiden tuonti.

Aiheeseen liittyvät artikkelit

Varaston seuranta

Sarjanumeroitu ja yhteisvarasto sekä se, mitä kumpikin raportoi.

Varastoartikkeli vs. SKU

Kumpi tietue kuuluu luoda.

API-avaimet

Tunnistautuminen, API-versiot ja kutsurajat.

API: Articles

Kaikki varastoartikkelien päätepisteet ja niiden skeemat.

Tervetuloa TWICE-dokumentaatioon

Liikkuminen TWICEssä

Järjestelmän ymmärtäminen

Päätä ensin tietueiden muoto

Miten se toimii

Käyttö

Varastoartikkelit

SKU:t

Asiakkaat

Tilausrivit

Tarkista koodit ja sähköpostit ennen lähetystä

Erän koko ja kutsurajat

Aiheeseen liittyvät artikkelit

Varaston seuranta

Varastoartikkeli vs. SKU

API-avaimet

API: Articles

​Päätä ensin tietueiden muoto

​Miten se toimii

​Käyttö

​Varastoartikkelit

​SKU:t

​Asiakkaat

​Tilausrivit

​Tarkista koodit ja sähköpostit ennen lähetystä

​Erän koko ja kutsurajat

​Aiheeseen liittyvät artikkelit

Varaston seuranta

Varastoartikkeli vs. SKU

API-avaimet

API: Articles

Päätä ensin tietueiden muoto

Miten se toimii

Käyttö

Varastoartikkelit

SKU:t

Asiakkaat

Tilausrivit

Tarkista koodit ja sähköpostit ennen lähetystä

Erän koko ja kutsurajat

Aiheeseen liittyvät artikkelit