> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SFTP-datarakenne

## 1. Johdanto

Tässä dokumentaatiossa kuvataan, miten datatiedostosi — **tuotteet**, **tilaukset**, **palautukset** ja niihin liittyvä data — tulee jäsentää SFTP-ympäristössämme, kun dedikoidulle tilallesi on tehty käyttöönotto.

Jos ylläpidät useita kauppoja tai sinulla on useita ympäristöjä (tuotanto, esituotanto jne.), luo kullekin erillinen alikansio (se voi olla myös eri brändejä tai eri maita).

### Hakemistorakenteen esimerkki

```
/root_space
    /shop_fr
    /shop_en
    /shop_it
```

***

## 2. Tiedonsiirtoaikataulu

Datatiedostot tulisi lähettää mieluiten **päivittäin** välillä:

* **klo 02:00**
* **klo 05:00**

Tämä aikataulu varmistaa optimaalisen käsittelyn ja datan sisäänottamisen.

***

## 3. Tiedostojen organisointistandardit

Luo jokaiseen kauppahakemistoon seuraavat kansiot:

* `products`
* `orders`
* `returns`
* `return_reasons` (valinnainen)
* `misc` (valinnainen)

**Huomiot:**

* `return_reasons`-kansiota käytetään vientitiedostoille, jotka sisältävät lisäpalautustietoja, kuten asiakkaiden ilmoittamat palautussyyt. Nämä viennit ovat valinnaisia.
* `misc`-kansio voi sisältää muita tiedostoja. Jos haluat käyttää tätä kansiota, keskustele hierarkiasta ja rakenteesta kanssamme etukäteen yhteensopivuuden varmistamiseksi.

Jokainen vienti tulee sijoittaa asianmukaiseen kansioon ja **nimetä aikaleimalla**.

### Tiedostonimen formaattiesimerkki

```
products_2025-01-15T02-00-00.csv
```

***

## 4. Vientisisällön vaatimukset

Yksityiskohtainen erittely odotetuista kentistä, formaateista ja rajoituksista kullekin datatyyppille on saatavilla **Datatiedonsiirtomalli**-dokumentaatiossa.

**Tuoteluettelovientin keskeiset vaatimukset:**

* Vie **kaikki tuotevariantit**, mukaan lukien loppuunmyydyt tuotteet
* Sisällytä **viimeisimmän muutoksen päivämäärä** -kenttä inkrementaalista käsittelyä varten
* Ylläpidä täydellisiä varianttitietoja asianmukaisen kokoanalyysin mahdollistamiseksi
* Lisää valinnainen deaktivointilippu Kleepin läsnäolon hallintaa varten

Katso mallista kattavat kenttämäärittelyt ja esimerkit.

***

## 5. Toistuvien tietojen käsittely vienneissä

Tietueet voivat laillisesti esiintyä useissa päivittäisissä vienneissä. Esimerkiksi tietty palautus voidaan sisällyttää useita kertoja eri tiedostoihin.

Sisäänottojärjestelmämme käsittelee kaksoiskappaleiden poistamisen automaattisesti ja käsittelee vain **kunkin tietueen uusimman version**.

***

## 6. Dataformaattiohjeet

Kaikki viennit tulee toimittaa **CSV**-formaatissa.

Excel-tiedostoja (`.xlsx`) ei suositella, koska ne aiheuttavat formaattiepäjohdonmukaisuuksia ja voivat hankaloittaa automatisoituja sisäänottoprosesseja.

* **Päivämäärä ja aika:** Käytä ISO 8601 -formaattia: `YYYY-MM-DDTHH:MM:SSZ`, esimerkki: `2025-01-15T14:30:00Z`
* **Koodaus:** UTF-8-koodaus kaikille tekstikentille, erikoismerkit oikein escape-merkittyinä CSV:ssä
* **Boolen arvot:** Käytä `true`/`false` (pieninä kirjaimina) tai `True`/`False`
* **Desimaaliluvut:** Käytä pistettä (`.`) desimaalieroittimena. Esimerkki: `129.99` eikä `129,99`
* **Null-arvot:** Tyhjä merkkijono puuttuville valinnaisille tekstikentille CSV:ssä, käytä null JSON:ssa

### Tiedostonimikäytäntö

***

SFTP-datarakenteen dokumentaatiossa määritellyn mukaisesti käytä seuraavaa formaattia:

```
{data_type}_{timestamp}.csv
```

Esimerkkejä:

* `products_2025-01-15T02-00-00.csv`
* `orders_2025-01-15T02-00-00.csv`
* `returns_2025-01-15T02-00-00.csv`

***

## 7. Historiallisen datan vieminen

Jos sinun täytyy toimittaa **historiallista dataa** (eli dataa, joka ei kuulu päivittäisiin vienteihin), voit viedä enintään **yhden vuoden historialliset tietueet** kaikille datatyypeille, mukaan lukien:

* **Tuotteet**
* **Tilaukset**
* **Palautukset**

Historialliset datajoukot voidaan lähettää joko **SFTP:n kautta** tai, jos se on kätevämpää, **jollakin muulla sovitulla tavalla**.

# Esimerkki täydellisestä SFTP-rakenteesta

```
/root_space
    /shop_fr
        /products
            products_2025-01-15T02-00-00.csv
            products_2025-01-16T02-00-00.csv
        /orders
            orders_2025-01-15T02-00-00.csv
            orders_2025-01-16T02-00-00.csv
        /returns
            returns_2025-01-15T02-00-00.csv
            returns_2025-01-16T02-00-00.csv
        /return_reasons
            return_reasons_2025-01-15T02-00-00.csv  (valinnainen)
        /misc
            (valinnainen, keskustele hierarkiasta kanssamme)

    /shop_en
        /products
        /orders
        /returns
        /return_reasons
        /misc

    /shop_it
        /products
        /orders
        /returns
        /return_reasons
        /misc

```

***