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

# Varastoartikkelin tila

> Näin varastoartikkelin tila (In/Out) seuraa automaattisesti, onko artikkeli hallussasi vai asiakkaalla.

export const stockItemStateDefinition = "Varastoartikkelin tila kertoo, onko artikkeli sisällä (hallussasi varastossa) vai ulkona (asiakkaan hallussa). Tila muuttuu automaattisesti tilausten toimitusten ja palautusten mukaan.";

<Frame caption="Inventaario > Varastoartikkelit > [Artikkeli] > Yleiset">
  <img src="https://mintcdn.com/twicecommerce/lZhc_tO8u1u_bL0Q/images/stock-item-general-tab.webp?fit=max&auto=format&n=lZhc_tO8u1u_bL0Q&q=85&s=e0a29bba3d2126e9149d978d008e2a62" alt="Varastoartikkelin tila Yleiset-välilehdellä" width="1920" height="1080" data-path="images/stock-item-general-tab.webp" />
</Frame>

## Määritelmä

<Tooltip tip={stockItemStateDefinition}>Varastoartikkelin tila</Tooltip> kertoo, missä varastoartikkeli fyysisesti on — hallussasi varastossa vai asiakkaalla. Tila on **automaattinen**: TWICE päivittää sen niiden tilausten keräilytapahtumien perusteella, joissa artikkeli on mukana.

**Kaksi tila-arvoa:**

* **In** — Artikkeli on hallussasi varastossa. Se voi silti olla sidottu tulevaan tilaukseen, mutta fyysisesti se on sinulla.
* **Out** — Artikkeli on asiakkaalla (vuokrattuna tai myytynä) tai muuten poissa.

Tila näkyy varastoartikkelilla merkkinä ja on saatavilla artikkelin API:n saatavuusjaksojen kautta.

## Tila vs. status

Nämä ovat kaksi toisistaan riippumatonta ulottuvuutta. Näet molemmat samalla artikkelilla.

| Ulottuvuus | Mitä se seuraa                | Arvot                                | Kuka asettaa                       |
| ---------- | ----------------------------- | ------------------------------------ | ---------------------------------- |
| **Tila**   | Missä artikkeli fyysisesti on | In / Out                             | Keräilyjärjestelmä (automaattinen) |
| **Status** | Artikkelin elinkaaren vaihe   | Aktiivinen / Ei aktiivinen / Luonnos | Työntekijä (käsin)                 |

Täysin kunnossa oleva pyörä, joka on parhaillaan vuokralla, näyttää **Active / Out**. Sama pyörä vuokrauksen jälkeen korjattavana näyttää **Inactive / In**. Lue lisää: [Varastoartikkelin status](/docs/fi/concepts/inventory/stock-item-status).

## Missä sitä käytetään?

Näet tilan kunkin varastoartikkelin kohdalla kohdassa **Inventaario > Varastoartikkelit** sekä artikkelin **Yleiset**-välilehdellä. Tila on myös suodatettava sarake varastoartikkelitaulukossa.

Tila vaikuttaa seuraaviin:

* **Myytävissä oleva saatavuus (ATS)** — vain artikkelit, jotka ovat **In** eivätkä ole sidottuja päällekkäisiin varauksiin, lasketaan saatavuuteen.
* **Palautusprosessi** — **Out**-tilassa olevat artikkelit odotetaan takaisin; tämä ohjaa palautusmuistutuksia ja myöhästymisraportointia.
* **Kalenterinäkymät** — näet, milloin artikkelien odotetaan palaavan **In**-tilaan.
* **Ristiriitojen tunnistus** — **Out**-tilassa olevan artikkelin siirtäminen merkitään huomiona, koska artikkeli on yhä asiakkaalla.

Lue lisää: [Varastoartikkelit — Yleiset-välilehti](/docs/fi/inventory/stock-items/general).

## Keskeiset ominaisuudet

| Ominaisuus                         | In                    | Out                    |
| ---------------------------------- | --------------------- | ---------------------- |
| Fyysinen sijainti                  | Hallussasi varastossa | Asiakkaalla            |
| Voidaanko noutaa uuteen tilaukseen | Kyllä                 | Ei ennen palautusta    |
| Lasketaan ATS:ään *juuri nyt*      | Kyllä                 | Ei                     |
| Asetettavissa käsin                | Ei (automaattinen)    | Ei (automaattinen)     |
| Näkyy kalenterissa varattuna       | Vain kun sidottu      | Aina palautukseen asti |

## Miten tila muuttuu

Tilasiirtymiä ohjaavat **keräilytapahtumat** niissä tilauksissa, jotka sisältävät varastoartikkelin. Olennaiset tapahtumat kirjataan artikkelin tapahtumalokiin.

### In → Out

Laukeaa, kun artikkeli **luovutetaan** tilauksella. Kirjatut tapahtumat:

* `handed_out` — nouto tai lähetys vuokrauksessa tai myynnissä.
* `assigned_to_order`, jota seuraa luovutus — artikkeli varattiin ja lähti sitten fyysisesti.

Luovutuksen jälkeen artikkeli kuuluu tilauksen ohjaamaan `unavailability`-jaksoon. ATS pienenee yhdellä kaikilla jaksoilla, jotka menevät päällekkäin tämän saatavuuskatkon kanssa.

### Out → In

Laukeaa, kun:

* `returned` — artikkeli palautetaan vuokratilauksella.
* Tilaus peruutetaan tai rivitieto poistetaan ennen noutoa (artikkeli ei koskaan lähtenyt).
* Keräily perutaan (työntekijä kumoaa luovutuksen hallinnassa).

Kun palautus tapahtuu, saatavuuskatko päättyy palautuksen aikaleimaan ja ATS palautuu.

```mermaid theme={null}
stateDiagram-v2
    [*] --> In
    In --> Out: luovutettu / lähetetty
    Out --> In: palautettu
    Out --> In: tilaus peruutettu
    Out --> In: luovutus kumottu
```

<Tip>
  Varastoartikkeli voi olla **In** ja silti **sidottu** tulevaan tilaukseen. Tila kuvaa vain fyysistä sijaintia, ei sitä, onko artikkeli varattu. Saatavuuslaskenta huomioi molemmat.
</Tip>

## Miten keräily ohjaa tilaa

Tilausrivit käyvät läpi nouto- ja palautusvaiheet:

1. **Varaus** — tilaus luodaan; artikkeli on **In**, mutta nyt kytkettynä varaavaan tilaukseen. ATS pienenee varatulta jaksolta.
2. **Luovutus** — työntekijä merkitsee rivin noudetuksi. Tapahtumaloki kirjaa `handed_out`. Tilaksi tulee **Out**.
3. **Asiakas pitää artikkelia** — tila pysyy **Out**. Myöhästymisraportit nostavat esiin myöhässä olevat artikkelit.
4. **Palautus** — työntekijä merkitsee rivin palautetuksi. Tapahtumaloki kirjaa `returned`. Tilaksi tulee **In**. Artikkeli vapautuu uudelleen vuokrattavaksi.
5. **Tilauksen päättäminen / peruutus** — sulkee tilauksen puolen. Jos rivi poistetaan ennen luovutusta, kirjataan `freed_from_order`.

**Myyntitilauksissa** vastaava kulku on keräily tai lähetys; lähetyksen jälkeen artikkeli on **Out** toistaiseksi, ja sen status asetetaan tyypillisesti käsin arvoon **Ei aktiivinen**, kun sitä ei enää seurata operatiivisesti.

**Yhteisvarastossa** (yksi tietue kattaa useita kappaleita) tila ja saatavuuskatkot toimivat **lukumäärien** eivätkä yksilöiden perusteella. **Out**-tilassa olevien kappaleiden määrä on niiden aktiivisten toimitettujen rivien summa, jotka kuluttavat tästä joukosta.

## ATS-laskenta

Myytävissä oleva saatavuus (ATS) vastaa kysymykseen: *kuinka monta tämän SKU:n kappaletta voin sitoa uuteen varaukseen pyydetyllä aikavälillä?*

SKU:n ATS aikavälillä `[start, end]`:

1. Aloita niiden linkitettyjen varastoartikkelien kokonaismäärästä, joilla `status = active` ja joiden palvelusijainti vastaa pyydettyä.
2. Vähennä kappaleet, jotka ovat **Out** ja joiden palautuspäivä on myöhemmin kuin `start`.
3. Vähennä kappaleet, jotka ovat **In** mutta sidottuja päällekkäisiin varauksiin (`scheduledEvents.type = reservation` sekä muista tilauksista tulevat saatavuuskatkot).
4. Jäljelle jäävä määrä on aikavälin ATS.

Moottori tarjoaa tuloksen artikkelin saatavuusvastauksen `temporalStock`-kentässä — neljänä `{ range, value }` -parien sarjana:

| Kenttä                 | Merkitys                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| `stockBalance`         | Kirjoilla olevat kappaleet aikavälillä (kokonaismäärä miinus toteutuneiden myyntien poistamat kappaleet). |
| `stockCommitted`       | Aikavälin kanssa päällekkäisiin tilauksiin ja varauksiin sidotut kappaleet.                               |
| `stockAvailableToSell` | `stockBalance − stockCommitted`, alarajana nolla. Tämä on ATS.                                            |
| `stockUtilisation`     | `stockCommitted / stockBalance` prosentteina.                                                             |

**Laskettu esimerkki.** SKU:lla on 10 aktiivista varastoartikkelia yhdessä sijainnissa:

* 3 on **Out** vuokrauksissa, jotka jatkuvat **15.1.** asti.
* 5 on **In** mutta sidottu tilaukseen, joka kattaa **10.–13.1.**
* Loput 2 ovat **In** eivätkä sidottuja.

| Aikaväli         | `stockBalance` | `stockCommitted`              | `stockAvailableToSell` |
| ---------------- | -------------- | ----------------------------- | ---------------------- |
| **1.1.–9.1.**    | 10             | 3 (vuokraukset)               | 7                      |
| **10.1.–13.1.**  | 10             | 8 (3 vuokrausta + 5 sidottua) | 2                      |
| **14.1.–15.1.**  | 10             | 3 (vuokraukset)               | 7                      |
| **16.1. alkaen** | 10             | 0                             | 10                     |

`stockBalance` pysyy koko ajan arvossa 10 — vuokraukset sitovat kappaleita mutta eivät poista niitä kirjoilta. Vain myynnit pienentävät saldoa. `stockUtilisation` on 10.–13.1. 80 %.

## Erikoistapaukset

<AccordionGroup>
  <Accordion title="Artikkeli katoaa Out-tilassa">
    Vaihda artikkelin **statukseksi** **Ei aktiivinen** Yleiset-välilehdellä ja kirjaa syy muistiinpanona. Tila pysyy **Out**, kunnes siihen liittyvä tilaus suljetaan tai peruutetaan — artikkeli on kirjattuna asiakkaan hallussa, kunnes suljet sen. Reskontra- ja tapahtumahistoria säilyvät.
  </Accordion>

  <Accordion title="Usean päivän vuokraus kalenterirajan yli">
    Tila asetetaan fyysisessä luovutuksessa, ei varauksen alkupäivänä. Artikkeli, joka on varattu 5.–12.1. mutta jota ei ole vielä noudettu, on 5.1. tilassa **In**. Luovutuksen jälkeen se pysyy **Out**-tilassa koko vuokra-ajan — päiviä, viikkoja tai kuukausia — kunnes se palautetaan.
  </Accordion>

  <Accordion title="Asiakas palauttaa toisen kahdesta artikkelista samalta riviltä">
    Osittaiset palautukset käsitellään yhteisvaraston riveillä kappalemäärinä ja sarjanumeroiduilla riveillä artikkeleittain. Palautetut kappaleet vaihtuvat takaisin **In**-tilaan; loput pysyvät **Out**-tilassa omaan palautukseensa asti.
  </Accordion>

  <Accordion title="Artikkeli palautetaan eri sijaintiin kuin mistä se lähti">
    Palautus muuttaa tilaksi **In** ja kirjaa `location_changed`-tapahtuman. Artikkelin `articleLocations` saa uuden jakson, joka alkaa palautuksen aikaleimasta uudessa palvelusijainnissa.
  </Accordion>

  <Accordion title="Keräily kumottiin vahingossa">
    Toimita rivi uudelleen. Artikkeli palaa **Out**-tilaan ja tapahtumaloki kirjaa uuden `handed_out`-tapahtuman. Aiempi kumoaminen jää lokiin jäljitettäväksi.
  </Accordion>

  <Accordion title="Artikkeli varattiin mutta sitä ei koskaan noudettu">
    Kunnes tilaus peruutetaan, artikkeli pysyy **In**-tilassa, mutta varaus vaikuttaa edelleen ATS:ään varatulla aikavälillä. Vapauta ATS peruuttamalla tilaus.
  </Accordion>
</AccordionGroup>

## Artikkelien haku tilan perusteella

Tila on saatavilla epäsuorasti `unavailability`-jaksojen ja `articleLocations`-taulukon kautta. Löydät parhaillaan **Out**-tilassa olevat artikkelit näin: listaa artikkelit aikavälillä, joka kattaa nykyhetken, ja suodata mukaan ne, joilla on aktiivinen `order`-tyyppinen saatavuuskatko. Tällaisessa katkossa luovutus on tapahtunut, palautus ei.

Hallinnassa: avaa **Inventaario > Varastoartikkelit** ja suodata **State**-sarake arvoon **Out**.

API:ssa: anna `dateRange`, joka kattaa haluamasi hetken. Parhaillaan ulkona olevilla varastoartikkeleilla on kyseisen hetken kattava saatavuuskatko, joka on peräisin luovutusvaiheessa olevalta tilausriviltä.

## Usein kysytyt kysymykset

<AccordionGroup>
  <Accordion title="Voinko muuttaa tilaa käsin?">
    Et. Tilan asettavat automaattisesti tilausten keräilyt ja palautukset. Muuta sitä toimittamalla tai palauttamalla kyseisen artikkelin tilausrivi.
  </Accordion>

  <Accordion title="Mitä jos artikkeli katoaa Out-tilassa?">
    Päivitä artikkelin **statukseksi** **Ei aktiivinen** Yleiset-välilehdellä ja kirjaa syy muistiinpanona. Tila pysyy **Out**, kunnes siihen liittyvä tilaus suljetaan tai peruutetaan.
  </Accordion>

  <Accordion title="Miten löydän kaikki parhaillaan Out-tilassa olevat artikkelit?">
    Avaa **Inventaario > Varastoartikkelit** ja suodata State-sarake arvoon **Out**. Näet kaikki asiakkaiden hallussa olevat artikkelit sekä niihin liittyvät tilaukset.
  </Accordion>

  <Accordion title="Vaikuttaako tila verkkokaupan saatavuuteen?">
    Kyllä. ATS-laskenta laskee mukaan vain artikkelit, jotka ovat **In** eivätkä sidottuja päällekkäisiin varauksiin pyydetyllä jaksolla. **Out**-tilassa olevat artikkelit, joiden palautus on pyydetyn alkupäivän jälkeen, vähennetään ATS:stä.
  </Accordion>

  <Accordion title="Artikkeli näkyy In-tilassa, mutta asiakkaalla on se yhä. Mitä tapahtui?">
    Todennäköisesti tilausrivi merkittiin hallinnassa palautetuksi ilman fyysistä palautusta. Avaa tilausrivi uudelleen tai selvitä asia tapahtumalokista; voit tarvittaessa toimittaa rivin uudelleen.
  </Accordion>
</AccordionGroup>

## Kehittäjän viitetiedot

Varastoartikkelin tila luetaan `articles`-päätepisteistä — suodata `dateRange`-arvolla, niin näet parhaillaan Out-tilassa olevat artikkelit.

<Card title="API: Articles" icon="code" href="https://server.twicecommerce.com/api/internal">
  Avaa päätepiste API-viitteessä.
</Card>

## Aiheeseen liittyvät käsitteet

<CardGroup cols={2}>
  <Card title="Varastoartikkelit" icon="box" href="/docs/fi/concepts/inventory/stock-items">
    Varastoartikkelin koko malli ja elinkaari
  </Card>

  <Card title="Varastoartikkelin status" icon="circle-info" href="/docs/fi/concepts/inventory/stock-item-status">
    Operatiivinen elinkaari (Active / Inactive / Draft)
  </Card>

  <Card title="Varastoartikkelin tapahtumat" icon="clock-rotate-left" href="/docs/fi/concepts/inventory/events">
    Miten tilaukset ja varaukset kirjaavat tapahtumia
  </Card>

  <Card title="Tilauksen elinkaari" icon="shopping-cart" href="/docs/fi/concepts/orders/order-lifecycle">
    Miten keräilyt ja palautukset ohjaavat tilan muutoksia
  </Card>
</CardGroup>