Tässä ohjeessa käydään käytännönläheisesti läpi, miten AI Commerce -järjestelmän pakkauspakkaaja (ostoskorin pakkauskoon laskenta) toimii, mistä se hakee mitat ja miten kauppias voi varmistaa, että laskenta antaa realistisen lopputuloksen. Kun mitat ovat kunnossa, voit luotettavammin rajata toimitustapoja, laskea toimituskuluja ja välittää oikeat tiedot integraatioihin.

Mitä pakkauspakkaaja tekee?

Pakkauspakkaaja laskee ostoskorille arvion tarvittavan paketin (lähetyksen) mitoista:

• pituus (length)
• leveys (width)
• korkeus (height)

Tätä pakkauskokoa käytetään tyypillisesti esimerkiksi:

• toimitustapojen rajaamiseen (esim. “max pituus 175 cm”)
• toimituskulujen laskentaan (erityisesti jos hinta riippuu mitoista tai tilavuuspainosta)
• integraatioihin (kuriirijärjestelmä, kuljetusliikkeen API, kassalla/ylläpidossa näkyvä “arvioitu pakkauskoko”)

Tärkeä periaate: pakkauspakkaaja ei ole “yksi staattinen taulukko”, vaan se laskee pakkauskoon aina ostoskorin senhetkisestä sisällöstä ja palauttaa tuloksen ostoskorin total-tietoihin.

Mistä mitat tulevat?

Pakkauspakkaaja tarvitsee jokaiselle tuotteelle mitat. Käytännön logiikka on:

1. Ensisijaisesti käytetään pakkausmittoja (packingSize), jos ne ovat saatavilla. Nämä ovat myyntipakkauksen/toimituspakkauksen mitat.
2. Jos pakkausmittoja ei ole, käytetään tuotteen mittoja (size) varavaihtoehtona.

Käytännössä tämä tarkoittaa myös sitä, että tuotteen mitat voivat olla 0, mutta jos packingSize on asetettu, pakkauspakkaaja käyttää silti pakkausmittoja toimituskoon laskentaan.

• Jos tuotteella on “tuotteen mitat” mutta se toimitetaan isommassa myyntipakkauksessa (esim. laatikko, rulla, suojapakkaus), pelkät tuotemitat voivat johtaa liian pieneen laskettuun pakkauskokoon.
• Tämän vuoksi pakkausmitat ovat paras tieto toimituslaskentaan.

Mittayksiköt (tärkeä debug-näkökulma)

Pakkauspakkaaja käsittelee tuotekohtaisia mittoja järjestelmän sisäisesti millimetreinä (mm), ja ostoskorin lopulliset length/width/height pyöristetään ylöspäin ja palautetaan tyypillisesti senttimetreinä (cm). Syynä on se, että kuriirit käyttävät senttimetrejä rajapinnoissa ja ERP:t varastoivat tuotteiden mitat useimmiten millimetreinä.

Siksi debugissa voi näkyä samaan aikaan esimerkiksi:

• items/base/volumeBased arvoja, jotka ovat millimetreinä (esim. 100.0)
• sekä lopulliset length/width/height, jotka ovat senttimetreinä (esim. 10.0)

Missä pakkauskoko näkyy?

API-sanomassa (JSON backendista)

Pakkauskoko palautetaan backendista osana ostoskorin vastausta (ostoskorin total-tietoihin). Tämä tarkoittaa, että pakkauskoko on nähtävissä myös JSON-muodossa.

Käytännössä tämä mahdollistaa kaksi asiaa:

• Kauppias tai integraatiokumppani voi tarkistaa arvot suoraan API-vastauksesta.
• Tieto voidaan myös näyttää käyttöliittymässä (esim. kassalla tai ylläpidossa), jos halutaan.

Vaikka et olisi kehittäjä, JSON-vastauksen voi nähdä kassan alareunassa kun kirjaudut järjestelmän valvojana käyttäjätilille.

Miten pakkauspakkaaja laskee koon käytännössä?

Vaihe 1: Tuotteet muutetaan “laatikoiksi”

Pakkauspakkaaja muodostaa ostoskorista sisäisen listan “laatikoita”:

• yksi laatikko per kappale (kpl) – jos tuotetta on ostoskorissa 45 kpl, syntyy 45 laatikkoa
• laatikon mitat tulevat ensisijaisesti packingSize-kentästä, muuten size-kentästä

Lopputulos on siis “pakattava laatikkolista”, ei yksittäinen summakaava.

Vaihe 2: Algoritmipohjainen pakkaus

Kun laatikot on muodostettu, pakkauspakkaaja yrittää löytää niille mahdollisimman kompaktin paketin:

• jokainen tuote voidaan kääntää 6 eri asentoon (orientaatiot)
• tuotteita asetellaan “riveihin” ja “kerroksiin” (pinoaminen kerroksittain)
• tavoitteena on pieni kokonaispaketti (minimoidaan erityisesti paketin “envelope” / ulkomitat)

Huomio: pakkauspakkaaja ei “tiedä” oikeita pahvilaatikkokokoja tai pakkausvaraa (täytemateriaali), vaan se laskee kompaktin arvion annettujen mittojen perusteella. Jos haluat ottaa pakkausvaran huomioon, tee se mieluummin tuotekohtaisissa packingSize-mitoissa.

Vaihe 3: Varamalli (jos pakkaus ei onnistu)

Jos algoritmipohjainen pakkaus ei jostain syystä pysty tuottamaan tulosta, järjestelmä siirtyy varamalliin, joka antaa “turvallisen arvion”:

• base: yksinkertainen perusarvio suurimpien mittojen perusteella (ei optimointia)
• volumeBased: tilavuuteen perustuva arvio, jossa lasketaan tuotteiden yhteistilavuus ja arvioidaan siitä “kuutiomainen” paketti

Molemmat ovat hyödyllisiä erityisesti debugissa, koska ne kertovat nopeasti, onko ongelma mitoissa vai pakkaamisessa.

Debug-kentät: hash, calcSource, calcReason, cacheHit

Ostoskorin pakkauskoon mukana palautuu myös debug-kenttiä, joiden tarkoitus on tehdä laskennan tulkinnasta läpinäkyvää. Nämä näkyvät tyypillisesti cart.total.size-objektissa.

• hash – ostoskorin “allekirjoitus” (hash), joka muodostetaan tuotetunnuksista, määristä ja käytetyistä mitoista. Jos ostoskorin sisältö tai määrä muuttuu, myös hashin pitäisi muuttua.
• calcSource – mistä lopputulos tuli:
  • packed = algoritmipohjainen pakkaus tuotti mitat
  • estimated = käytettiin varamallia
  • empty = kori tyhjä / ei pakattavia laatikoita
• calcReason – tarkempi syy/selite, miksi kyseinen polku valittiin (esim. packer_success tai packer_failed_fallback_to_volumeBased).
• cacheHit – kertoo, tuliko tulos välimuistista. Tällä hetkellä pakkauskoon laskenta tehdään normaalisti joka laskennassa ja cacheHit on käytännössä false, mutta kenttä on mukana, jotta välimuisti voidaan halutessa ottaa käyttöön hallitusti.

Debug-vinkki: jos muutat ostoskorin määriä ja huomaat, ettei pakkauskoko muutu, tarkista ensimmäisenä hash. Jos hash ei muutu, katse kannattaa kohdistaa siihen, päivittyikö ostoskori oikeasti (tai onko näkymässä vanha vastaus).

Näin varmistat, että pakkauskoko on realistinen

Alla oleva tarkistuslista auttaa paikallistamaan yleisimmät syyt epärealistiseen pakkauskokoon ja testaamaan laskentaa käytännössä.

1. Tarkista, että mitat ovat oikeasti toimitusmitat
   Varmista, ovatko mitat tallennettu tuotteen fyysisinä mittoina (size) vai myyntipakkauksen mittoina (packingSize).
   • Jos tuotteella on erillinen pakkaus (laatikko, rulla, suojapakkaus), pakkausmitat ovat lähes aina parempi tieto toimituslaskentaan.
   • Jos mitat puuttuvat tai ovat nollia, tulos voi jäädä liian pieneksi (varsinkin jos käytössä ei ole packingSize-tietoa).
2. Tarkista yksiköt ja mittakaava
   Varmista, millä yksiköillä mitat on tallennettu.
   • Tuotekohtaiset mitat on tyypillisesti tarkoitettu millimetreinä (mm). Ostoskorin lopputulos näytetään usein senttimetreinä (cm).
   • Esimerkiksi “100 mm” vs “100 cm” -sekaannus tekee tuloksesta täysin epärealistisen.
3. Testaa tyypilliset ostoskorit
   Tee testikoreja, jotka vastaavat oikeita ostotilanteita.
   • Tee testikori, joka vastaa yleisintä tilausta (esim. 1–5 tuotetta).
   • Tee testikori, jossa on paljon kappaleita (esim. 30–60 kpl), jotta näet miten pakkaus käyttäytyy massalla.
   • Tarkista samalla hash: sen pitäisi muuttua, kun muutat määriä.
4. Vertaile laskettua pakkauskokoa toteutuneeseen lähetykseen
   Kun ensimmäiset lähetykset on tehty, vertaa laskettua kokoa siihen, millaiseen pakettiin tavara oikeasti meni.
   • Jos toistuvasti tulee poikkeamaa, syy löytyy lähes aina mitoista (tai siitä, että käytetään tuotemittoja vaikka pitäisi käyttää pakkausmittoja).
5. Tarkista debug-kentistä laskentapolku
   Jos epäilet tulosta, katso erityisesti:
   • calcSource (packed / estimated)
   • calcReason (miksi)
   • items, base, volumeBased (mittojen suuruusluokka – huomaa yksiköt)

Miten pakkauskokoa voi hyödyntää kassalla ja integraatioissa?

Koska pakkauskoko palautuu API:ssa, sitä voidaan hyödyntää esimerkiksi näin:

• Kassalla näkyvä arvio: “Arvioitu pakkauskoko: 50 × 40 × 30 cm”
• Toimitustapojen rajoitteet: estetään toimitustapa, jos ylittää sallitut mitat
• Hintalaskenta mittojen mukaan: jos kuriiri tai integraatio tukee hinnoittelua mitoilla/tilavuuspainolla
• Lähetetietojen rikastus: välitetään pakkauskoko kuljetusliikkeen järjestelmälle automaattisesti

Tämä on erityisen hyödyllistä, jos käytössä on toimitustapoja, joissa:

• maksimit mittojen mukaan ovat tiukat
• hinta muodostuu mittojen / tilavuuspainon perusteella
• halutaan automatisoida mahdollisimman paljon ilman manuaalista pakettikoon arviointia

Yhteenveto

• Pakkauspakkaaja laskee ostoskorin pakkauskoon ostoskorin sisällöstä ja palauttaa sen ostoskorin total-tietoihin.
• Pakkauskoko näkyy backendin API-vastauksessa JSON-muodossa ja sitä voi hyödyntää myös käyttöliittymässä tai integraatioissa.
• Mitat tulevat ensisijaisesti packingSize-kentästä ja varavaihtoehtona size-kentästä.
• Pakkaus käyttää algoritmia (6 orientaatiota, rivit/kerrokset) ja tarvittaessa varamallia (base / volumeBased).
• Debug-kentät hash, calcSource, calcReason ja cacheHit auttavat ymmärtämään, mistä tulos tuli ja muuttuiko kori oikeasti.
• Realistinen lopputulos riippuu siitä, että tuotteilla (ja mielellään pakkausmitoilla) on oikeat, toimitusta vastaavat mitat.

Suositeltu seuraava toimenpide: tee muutama testikori (pieni ja “paljon kappaleita”), tarkista pakkauskoko API-vastauksesta sekä debug-kentistä (calcSource/calcReason/hash) ja vertaa tuloksia toteutuneisiin lähetyksiin.

FAQ – Pakkauspakkaaja

1) Mikä on pakkauspakkaaja?

Pakkauspakkaaja laskee ostoskorin tuotteista arvion paketin mitoista (pituus, leveys, korkeus), jotta toimitustapoja ja toimituskuluja voidaan ohjata mittojen perusteella.

2) Mistä pakkauspakkaaja saa mitat?

Mitat tulevat tuotteiden mitoista. Kun pakkausmitat (packingSize) ovat käytössä, niitä käytetään ensisijaisesti. Jos pakkausmittoja ei ole, käytetään tuotteen mittoja (size) varavaihtoehtona.

3) Missä pakkauskoko näkyy?

Pakkauskoko palautuu backendista API-vastauksessa JSON-muodossa (ostoskorin total-tietoihin). Tarvittaessa integraatiokumppani voi näyttää sen myös käyttöliittymässä (esim. kassalla tai ylläpidossa).

4) Mitä hash, calcSource, calcReason ja cacheHit tarkoittavat?

Ne ovat debug-kenttiä:

• hash kertoo, mihin ostoskorin sisältöön (tuotteet + määrät + mitat) laskenta perustui
• calcSource kertoo, oliko tulos pakattu (packed) vai arvioitu (estimated)
• calcReason kertoo tarkemman syyn/polun
• cacheHit kertoo, tuliko tulos välimuistista (tällä hetkellä käytännössä false)

5) Miksi pakkauskoko voi olla epärealistinen?

Yleisin syy on väärät tai puuttuvat mitat:

• tuotteella on vain tuotemitat, vaikka toimitus tapahtuu isommassa myyntipakkauksessa → lisää packingSize
• mittayksiköt ovat väärin (mm vs cm)
• mitat ovat nollia → laskenta voi “alistaa” tuotteen liian pieneksi

Avainsanat

• pakkauspakkaaja
• pakkauskoko
• packingSize
• size
• hash
• calcSource
• calcReason
• cacheHit
• ostoskori
• toimitusmitat
• pakkausmitat
• tuotemitat
• JSON API
• toimitustapojen rajoitteet
• toimituskulut ja mitat