> ## 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. # Listaus > Katalogisi myytävä tuotetarjoama, joka määrittää, mitä asiakkaat voivat ostaa tai vuokrata. Listaustaulukko Adminissa ## Määritelmä **Vertaus:** Listaus on tuotteesi näyteikkunaversio. SKU:t (varastonimikkeet) ja varastoartikkelit kuvaavat, mitä omistat; listaus kuvaa, mitä myyt — nimen, kuvat, hinnat, kestot ja sen, missä se näkyy. **Erityistä TWICEssä:** Listaus ei ole varastoa. Saatavuus johdetaan reaaliajassa niistä varastoartikkeleista, jotka on liitetty siihen keräilysääntöjen kautta. Kaksi listausta voi kohdistua samoihin fyysisiin kappaleisiin (esimerkiksi saman pyörän päivävuokraus- ja pitkäaikaislistaus). ## Listaus vs. SKU vs. varastoartikkeli | Käsite | Mitä se edustaa | Missä se sijaitsee | | ----------------------- | ------------------------------------------------------------------------------- | ------------------ | | Listaus (katalogikohde) | Asiakkaalle näkyvä tarjoama: nimi, media, hinnoittelu, variantit, myyntikanavat | Katalogi | | SKU | Sisäinen tuotemäärittely: koodi, attribuutit, keräilypohja | Inventaario | | Varastoartikkeli | Fyysinen kappale (tai koottu määrä), jonka voi varata | Varasto | Listaus yltää varastoon **keräilysääntöjen** kautta, ei suorilla viiteavaimilla. Sääntö sanoo: ”varaa tämän listauksen toimittamiseksi 1 kappale, joka vastaa ehtoa `attribute:bike_size = M`”. Sääntö ratkaistaan vastaaviksi varastoartikkeleiksi tilaushetkellä, minkä vuoksi yksi listaus voi hyödyntää useaa SKU:ta ja moni SKU voi toimia usean listauksen pohjana. Katso myös: [SKU](/docs/fi/concepts/inventory/skus), [Varastoartikkeli](/docs/fi/concepts/inventory/stock-items). ## Missä sitä käytetään? * **Katalogin hallinta** — luo, jäsennä ja julkaise tuotteet, joita asiakkaat voivat tilata * **Verkkokauppa** — kaikki verkkokanavaan julkaistu näkyy listauksen pohjalta * **Tilausten luonti** — Adminin tilausluonnos ja verkkokaupan kassa lähtevät listauksesta * **Hinnoittelu** — liitä listaukseen yksi tai useampi hintataulukko, jotka määrittävät vuokra-, myynti- ja kestotilaushinnat * **Variantit** — tarjoa koko, väri tai muita ulottuvuuksia saman listauksen sisällä * **Saatavuus** — laske reaaliaikainen myytävissä oleva määrä leikkaamalla keräilysäännöt varastoartikkeleiden kanssa * **Kokoelmat** — ryhmittele listauksia verkkokaupan navigointia ja esillepanoa varten * **Myyntikanavat** — määritä, näkyykö listaus Adminissa ja verkkokaupassa * **Lisäosat** — merkitse listaus vain lisäosaksi tai liitä lisäosia muihin listauksiin * **SEO ja markkinointi** — osoitepolku, sivun otsikko, metakuvaus, OpenGraph-kuva, `noindex` ## Keskeiset ominaisuudet ### Tunnistetiedot ja sisältö | Ominaisuus | Tyyppi | Kuvaus | | -------------------- | ---------------------- | ----------------------------------------------------------------------- | | `id` | UUID | Palvelimen luoma tunniste | | `name` | Merkkijono | Asiakkaille näkyvä otsikko | | `internalName` | Merkkijono \| null | Vapaaehtoinen sisäinen nimike, joka näkyy vain henkilökunnalle | | `description` | Merkkijono \| null | Pelkkä tekstikuvaus. Vanhentunut — käytä mieluummin `descriptionJson` | | `descriptionJson` | JSON | Rikastetun tekstin kuvaus, jota verkkokauppa käyttää | | `sections` | `CatalogItemSection[]` | Järjestetyt sisältöosiot (`heading`, `content`, `orderIndex`) | | `taxonomyCategoryId` | Merkkijono \| null | Linkki kategoriataksonomian solmuun | | `tags` | `Tag[]` | Katalogitason tunnisteet. Älykkäät kokoelmat kohdistuvat näihin | | `attributes` | `ResourceAttribute[]` | Mukautettujen attribuuttien arvot suodatukseen ja tuotesivun esitykseen | ### Tila ja näkyvyys | Ominaisuus | Tyyppi | Kuvaus | | -------------------- | --------------------------------------- | -------------------------------------------------------------- | | `status` | Enum: `active` \| `draft` \| `template` | Julkaisutila. Adminin käyttöliittymä näyttää kaksi vaihtoehtoa | | `salesChannelAdmin` | Totuusarvo | Näkyy, kun tilauksia luodaan Adminissa | | `salesChannelOnline` | Totuusarvo | Näkyy verkkokaupassa | Adminin tilavalitsin näyttää vain vaihtoehdot **Public** (`active`) ja **Luonnos** (`draft`). Arvo `template` on varattu järjestelmäpohjille, eikä se ole käyttäjälle näkyvä julkaisutila. Arkistointi on eri ulottuvuus kuin julkaisutila. Aseta listaus luonnostilaan, kun haluat pitää sen katalogissa mutta poissa verkkokaupasta; arkistoi se, kun haluat poistaa sen käytöstä kokonaan. Katso [Arkistointi ja poistaminen](/docs/fi/concepts/repeating-patterns/archiving-and-deletion). ### Hinnoittelu ja verot | Ominaisuus | Tyyppi | Kuvaus | | ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `pricingTables` | `PricingTable[]` | Yksi tai useampi listaukseen liitetty hintataulukko. Taulukot voivat olla itsenäisiä tai jaettuja | | `taxes` | `CatalogItemTax[]` | Listaukseen sovellettavat verokannat, mahdollisine sijaintikohtaisine ohituksineen | | `bookingDeposit` | Int ≥ 0 \| null | Palautettava pantti (pienimpinä yksikköinä), jota pyydetään, kun listaus varataan. `null` tarkoittaa, ettei panttia ole | Hintaa ei koskaan tallenneta suoraan listaukselle. Kaikki hinnoittelu on liitetyissä hintataulukoissa (varaus-, myynti- ja kestotilausriveillä). Katso [Hintataulukko-käsite](/docs/fi/concepts/catalog/price-tables). ### Rajoitukset ja varausten toiminta | Ominaisuus | Tyyppi | Kuvaus | | -------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `minBookingDuration` | `{ value, unit }` \| null | Lyhin sallittu vuokra-aika | | `maxBookingDuration` | `{ value, unit }` \| null | Pisin sallittu vuokra-aika | | `bookingDurationIncrement` | `{ value, unit }` \| null | Rajaa kertoimeen perustuvat varaukset tämän keston täysiin kerrannaisiin | | `orderDeadline` | OrderDeadline \| null | Viimeisin hetki, jolloin tilauksen voi tehdä suhteessa varauksen alkuun. Joko `{ type: 'absolute', value, unit }` (kiinteä aikaväli ennen alkua; `unit` on `minutes`, `hours` tai `days`) tai `{ type: 'relative', daysBefore, time }` (kellonaikaan sidottu raja aiempana päivänä) | `unit` on jokin arvoista `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`. ### Varasto ja keräily | Ominaisuus | Tyyppi | Kuvaus | | -------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inventoryTrackingEnabled` | Totuusarvo | Seurataanko saatavuutta varastoartikkeleista | | `rules` | `CatalogItemRule[]` | Peruskeräilysäännöt. Jokainen sääntö määrittää `quantity`-määrän ja `conditions`-ehdot, jotka kohdistavat varastoartikkeleita attribuutin, artikkelikoodin, SKU-koodin, artikkelin nimen tai SKU:n nimen perusteella | | `rules[].variantRules` | `CatalogItemVariantRule[]` | Perussäännön varianttikohtaiset ohitukset | | `rules[].revenueSplitRate` | Luku \| null | Vapaaehtoinen jakosuhde, jota tuottojen jakoraportointi käyttää | | `serviceLocationLinks` | `CatalogItemServiceLocationLink[]` | Sijainnit, joista tämä listaus voidaan toimittaa | ### Variantit | Ominaisuus | Tyyppi | Kuvaus | | ---------- | ---------------------- | ----------------------------------------------------------------------------------------------------- | | `variants` | `CatalogItemVariant[]` | Yksi tai useampi varianttiulottuvuus. Kullakin on `name` (esimerkiksi `Size`) ja järjestetyt `values` | Listausta, jolla ei ole variantteja, käsitellään yhden SKU:n tarjoamana. Katso [Variantti-käsite](/docs/fi/concepts/catalog/variants). ### Media, dokumentit ja SEO | Ominaisuus | Tyyppi | Kuvaus | | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `media` | `CatalogItemMediaLinks[]` | Järjestetyt kuva- ja videotiedostot | | `documents` | `CatalogItemDocument[]` | Liitetyt tiedostot. Jokaisella tiedostolla kaksi toisistaan riippumatonta merkintää: `copyToOrder` kopioi sen tilauksen Dokumentit-välilehdelle, `attachToOrderConfirmation` liittää sen tilaussähköposteihin | | `slugs` | Merkkijono\[] | Verkkokaupan osoitepolut. Ensimmäinen on ensisijainen (canonical) polku, jota käytetään linkeissä ja SEO-tunnisteissa. Muut ovat vaihtoehtoisia polkuja, jotka myös avaavat listauksen. Muodostetaan automaattisesti listauksen nimestä ensimmäisellä tallennuksella, jos tyhjä | | `pageTitle` | Merkkijono \| null | SEO-`` | | `metaDescription` | Merkkijono \| null | SEO-metakuvaus | | `ogTitle` / `ogDescription` / `ogImage` | Merkkijono / FileResource | OpenGraph-metatiedot sosiaalisen median esikatseluihin | | `noindex` | Totuusarvo | Estä hakukoneindeksointi | ### Lisäosat ja liittyvät listaukset | Ominaisuus | Tyyppi | Kuvaus | | ---------------------- | ---------------------------- | ---------------------------------------------------- | | `addonOnly` | Totuusarvo | Kun `true`, listauksen voi ostaa vain lisäosana | | `addonPricingMode` | `standalone` \| `percentage` | Miten sen hinta lasketaan lisäosana käytettäessä | | `addonPricePercentage` | Kokonaisluku 1–200 \| null | Pakollinen, kun `addonPricingMode = 'percentage'` | | `relatedListingIds` | Merkkijono\[] | Enintään 100 listausta, jotka näytetään suosituksina | ### Kassavaatimukset | Ominaisuus | Tyyppi | Kuvaus | | ---------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- | | `checkoutRequirements` | `CheckoutRequirements` | Listauskohtaiset pakolliset asiakastiedot ja suostumustekstit. Käyttää oletuksena kaupan oletusasetuksia | ## Suhteet <AccordionGroup> <Accordion title="Kuuluu katalogiin"> Listaus on yksi rivi katalogissasi. Se on esillepanon yksikkö ja se, mitä tilataan. Listauksia listataan, suodatetaan ja ryhmitellään kohdassa **Katalogi > Listaukset**. </Accordion> <Accordion title="Kohdistuu SKU:ihin ja varastoartikkeleihin keräilysääntöjen kautta"> Listaus ei osoita yhteen SKU:hun. Jokainen listauksen keräilysääntö kohdistaa yhden tai useamman varastoartikkelin attribuutin, SKU-koodin tai muiden suodattimien perusteella. Listauksen saatavuus on näiden osumien ja kalenterivarausten leikkaus. </Accordion> <Accordion title="Näkyy kokoelmissa"> Listaus voi kuulua rajattomaan määrään kokoelmia — joko käsin lisättynä (manuaalinen kokoelma) tai tunnisteen perusteella (älykäs kokoelma). Katso [Kokoelma-käsite](/docs/fi/concepts/catalog/collections). </Accordion> <Accordion title="Julkaistaan myyntikanaviin"> Kaksi totuusarvokenttää määrittää, missä listausta tarjotaan: Admin ja verkkokauppa. Molempien poistaminen käytöstä pitää listauksen katalogissa mutta poissa myynnistä. Katso [Verkkokauppa-käsite](/docs/fi/concepts/sales-channels/online-store). </Accordion> <Accordion title="Liitetty palvelusijainteihin"> Jokainen `CatalogItemServiceLocationLink` ilmoittaa sijainnin, josta listaus voidaan toimittaa. Verkkokaupan saatavuussuodattimet ja tilausten reititys käyttävät näitä. </Accordion> <Accordion title="Hinnoitellaan hintataulukoilla"> Kaikki hinnat ovat liitetyissä hintataulukoissa. Listauksella on yleensä oletustaulukko (aina voimassa) ja mahdollisia päivämäärään sidottuja taulukoita kampanjoita tai kausihinnoittelua varten. </Accordion> </AccordionGroup> ```mermaid theme={null} %%{init: {'flowchart': {'nodeSpacing': 20, 'rankSpacing': 30}}}%% flowchart TB subgraph CatalogBox[" "] Collection["Kokoelma"] Listing["**Listaus**"] PriceTable["Hintataulukko"] Collection ~~~ Listing ~~~ PriceTable end Rules["Keräilysäännöt"] SKU[SKU] StockItems[Varastoartikkelit] subgraph ChannelsBox[" "] direction TB Admin[Admin] OnlineStore[Verkkokauppa] Admin ~~~ OnlineStore end Listing -->|määrittää| Rules Rules -->|kohdistaa attribuutin / SKU-koodin mukaan| SKU SKU -->|omistaa kappaleita| StockItems Listing -.->|julkaistaan| ChannelsBox Listing -->|hinnoitellaan| PriceTable style CatalogBox fill:#0000000d,stroke:#888,stroke-width:2px style Listing fill:#3b82f633,stroke:#3b82f6,stroke-width:3px,font-weight:bold style Collection fill:#0000000a,stroke:#999,stroke-width:1px style PriceTable fill:#0000000a,stroke:#999,stroke-width:1px style Rules fill:#a78bfa33,stroke:#a78bfa,stroke-width:2px style SKU fill:#10b98133,stroke:#10b981,stroke-width:2px style StockItems fill:#10b98133,stroke:#10b981,stroke-width:2px style ChannelsBox fill:#f59e0b1a,stroke:#f59e0b,stroke-width:2px ``` ## Listauksen tietovälilehdet Kun avaat listauksen Adminissa, resurssisivulla on seuraavat välilehdet: | Välilehti | Mitä siinä määritetään | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Yleiset | Nimi, sisäinen nimi, kuvaus, osiot, media, taksonomiakategoria, tila, tunnisteet | | Attribuutit | Mukautettujen attribuuttien arvot (linkittyvät attribuuttiryhmiin) | | Variantit | Varianttiulottuvuudet, arvot ja järjestys | | Hinnoittelu | Yksi tai useampi hintataulukko (varaus-, myynti- ja kestotilausrivit; mahdolliset varianttikohtaiset kertoimet) sekä varauspantti | | Rajoitukset | `minBookingDuration`, `maxBookingDuration`, `bookingDurationIncrement`, `orderDeadline` | | Keräily | Peruskeräilysäännöt, varianttisäännöt ja tuottojen jakosuhteet | | Viivakoodit | Viivakoodit, jotka johtavat tähän listaukseen skannattaessa | | Julkaisu | Myyntikanavien kytkimet (Admin / verkkokauppa) ja palvelusijainnit | | Kassa-asetukset | Listauskohtaiset kassavaatimukset (pakolliset kentät, suostumukset) | | Lisäosien asetukset | Miten listaus käyttäytyy lisäosana: näkyminen vain lisäosana ja lisäosan hinnoittelutapa | | Suositukset | Liitä lisäosia tähän listaukseen ja valitse tuotesivulla näytettävät liittyvät listaukset | | Markkinointi | SEO-kentät: osoitepolku, sivun otsikko, metakuvaus, OpenGraph | | Dokumentit | Liitetyt tiedostot, joista kukin voidaan merkitä **Kopioi tilaukseen** (kopio päätyy tilauksen Dokumentit-välilehdelle) tai **Attach to order confirmation** (liitetään tilaussähköposteihin) | | Tilausloki | Tilaukset, jotka sisältävät tämän listauksen | | Toimintaloki | Auditointiloki tämän listauksen muutoksista | ## Saatavuuden laskenta Saatavuutta (myytävissä oleva määrä) **ei koskaan tallenneta** listaukselle. Se lasketaan pyynnöstä katalogin saatavuuspäätepisteillä: * `GET /catalog/:id/quantity` — listauksen saatavilla olevat kappaleet päivämäärävälillä ja valituissa palvelusijainneissa * `GET /catalog/:id/available-by-variant-value-groups` — erittely varianttiarvojen yhdistelmittäin Laskenta käy läpi listauksen keräilysäännöt, ratkaisee kunkin säännön `conditions`-ehdot varastoartikkeleita vasten ja vähentää pyydetyn aikaikkunan olemassa olevat varaukset. Listausta, jolla `inventoryTrackingEnabled = false`, käsitellään rajattomasti saatavilla olevana. ## Elinkaari <Steps> <Step title="Luonti"> Luo listaus tyhjästä, pohjasta, monistamalla olemassa oleva listaus tai suoraan SKU:sta (`POST /catalog/from-article/:articleId`). <AccordionGroup> <Accordion title="Mitkä tiedot ovat vähintään pakollisia?"> Vain `name` on ehdottomasti pakollinen. Jotta listaus olisi ostettavissa, tarvitset lisäksi vähintään yhden keräilysäännön (tai arvon `inventoryTrackingEnabled = false`), yhden hintataulukon ja vähintään yhden käytössä olevan myyntikanavan. </Accordion> <Accordion title="Mikä on alkutila?"> Uudet listaukset luodaan arvolla `status = 'draft'`. Ne eivät näy asiakkaille, ennen kuin vaihdat tilaksi Public. </Accordion> <Accordion title="Voiko luonnin automatisoida?"> Kyllä. Käytä kutsua `POST /catalog/` suoraan luontiin, `POST /catalog/many` massatuontiin tai `POST /catalog/from-article/:articleId` listauksen luomiseen olemassa olevasta SKU:sta. </Accordion> </AccordionGroup> </Step> <Step title="Julkaisu"> Vaihda `status`-arvoksi `active` ja ota käyttöön ne myyntikanavat, joissa haluat listauksen näkyvän. <AccordionGroup> <Accordion title="Missä julkinen listaus näkyy?"> Verkkokaupassa, jos `salesChannelOnline = true`, ja Adminin tilausluonnoksessa, jos `salesChannelAdmin = true`. </Accordion> <Accordion title="Mikä estää julkaisun käytännössä?"> Ei mikään API:n osalta. Mutta listaus, jolla ei ole keräilysääntöä ja jolla `inventoryTrackingEnabled = true`, näyttää saatavuudeksi 0. Listausta ilman hintataulukkoa ei voi hinnoitella kassalla. </Accordion> </AccordionGroup> </Step> <Step title="Päivitys"> Useimpia kenttiä voi päivittää kutsulla `PUT /catalog/:id`. Säännöillä, varianteilla, hintataulukoilla ja viivakoodeilla on omat sisäkkäiset päätepisteensä. <AccordionGroup> <Accordion title="Mitkä muutokset ovat turvallisia julkiselle listaukselle?"> Sisältökentät (nimi, kuvaus, media, SEO) ovat turvallisia. Sääntömuutokset vaikuttavat vain tuleviin saatavuuslaskentoihin — olemassa olevat tilaukset säilyttävät tallentamansa listaustiedot. </Accordion> <Accordion title="Entä hintamuutokset?"> Lisää uusi päivämäärään sidottu hintataulukko oletustaulukon muokkaamisen sijaan, jos hinnoittelun on tarkoitus alkaa vasta tulevaisuudessa. Olemassa olevia tilauksia ei hinnoitella takautuvasti. </Accordion> </AccordionGroup> </Step> <Step title="Käytöstä poisto"> Aseta `status = 'draft'`, kun haluat ottaa listauksen pois verkosta mutta säilyttää sen historian, tai poista se kutsulla `DELETE /catalog/:id`. Tilauksissa viitatut listaukset säilytetään historiaraportointia varten myös poiston jälkeen. </Step> </Steps> ## Usein kysytyt kysymykset <AccordionGroup> <Accordion title="Mikä ero on listauksella ja SKU:lla?"> **SKU** on varastomäärittely — koodi, joka yksilöi omistamasi kappaletyypin. **Listaus** on myytävä tarjoama katalogissasi. Yksi SKU voi toimia usean listauksen pohjana (esimerkiksi saman pyörän päivävuokraus, viikkovuokraus ja suoramyynti). Yksi listaus voi kohdistua useaan SKU:hun keräilysääntöjen kautta. </Accordion> <Accordion title="Voinko myydä samaa fyysistä tuotetta eri hinnoilla?"> Kyllä. Luo yksi listaus tarjoamaa kohden ja liitä kuhunkin eri hintataulukko, tai liitä samaan listaukseen useita hintataulukoita, joiden `availabilityRange`-ikkunat eivät mene päällekkäin. </Accordion> <Accordion title="Miten saatavuus toimii yksilöidyn varaston kanssa?"> Jokainen keräilysääntö kohdistuu joukkoon mahdollisia varastoartikkeleita attribuutti- tai koodivastaavuuden perusteella. Listauksen myytävissä oleva määrä tietyllä aikavälillä on mahdollisten varastoartikkelien lukumäärä miinus kyseiselle välille jo varatut kappaleet. </Accordion> <Accordion title="Mitä `template`-tila tarkoittaa?"> `template` on sisäinen tila, jota järjestelmäpohjat käyttävät. Se ei näy Adminin tilavalitsimessa eikä ole käyttäjälle näkyvä julkaisutila. </Accordion> <Accordion title="Voiko listaus olla sekä vuokraus että myynti?"> Kyllä. Hintataulukkomalli sisältää erilliset `bookingPricingRows`-, `salesPricingRows`- ja `subscriptionPricingRows`-rivit. Määritä taulukossa kytkimillä `bookingsEnabled`, `salesEnabled` ja `subscriptionsEnabled`, mitä ostotapoja tarjotaan. </Accordion> <Accordion title="Miksi listauksella ei ole `price`-kenttää?"> Kaikki hintalogiikka on hintataulukoissa, jotta yhdelle listaukselle voi olla samanaikaisesti useita hinnastoja, päivämäärään sidottuja kampanjoita ja varianttikohtaisia kertoimia. Listaus ilman hintataulukkoa on hinnoittelematon. </Accordion> </AccordionGroup> ## Kehittäjän viite Listaukset näkyvät API:ssa `catalog`-kohteina. <Card title="API: Catalog" icon="code" href="https://server.twicecommerce.com/api/internal"> Avaa päätepiste API-referenssissä. </Card> ## Aiheeseen liittyvää <CardGroup cols={2}> <Card title="Variantit" icon="layer-group" href="/docs/fi/concepts/catalog/variants"> Koko, väri ja muut ulottuvuudet listauksen sisällä </Card> <Card title="Hintataulukot" icon="table" href="/docs/fi/concepts/catalog/price-tables"> Uudelleenkäytettävät hinnoittelurakenteet, jotka liitetään listauksiin </Card> <Card title="Kokoelmat" icon="folder" href="/docs/fi/concepts/catalog/collections"> Listausten manuaaliset ja älykkäät ryhmittelyt </Card> <Card title="SKU" icon="barcode" href="/docs/fi/concepts/inventory/skus"> Varastomäärittely, josta listaus toimitetaan </Card> <Card title="Varastoartikkeli" icon="box" href="/docs/fi/concepts/inventory/stock-items"> Fyysiset kappaleet, jotka varataan, kun listaus tilataan </Card> <Card title="Verkkokauppa" icon="store" href="/docs/fi/concepts/sales-channels/online-store"> Missä julkiset listaukset näkyvät asiakkaille </Card> </CardGroup>