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

# Struktura danych SFTP

## 1. Wprowadzenie

Niniejsza dokumentacja opisuje, jak strukturować pliki danych — **produkty**, **zamówienia**, **zwroty** i powiązane dane — w naszym środowisku SFTP po udostępnieniu Twojej dedykowanej przestrzeni.

Jeśli obsługujesz wiele sklepów lub posiadasz wiele środowisk (prod, preprod itd.), utwórz oddzielny podfolder dla każdego z nich (mogą to być również różne marki, różne kraje itd.).

### Przykładowa struktura katalogów

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

***

## 2. Harmonogram transmisji danych

Pliki danych powinny być idealnie przesyłane **codziennie** w godzinach:

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

Ten przedział czasowy zapewnia optymalne przetwarzanie i ingestion danych.

***

## 3. Standardy organizacji plików

W każdym katalogu sklepu utwórz następujące foldery:

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

**Uwagi:**

* Folder `return_reasons` jest używany do plików eksportu zawierających dodatkowe dane dotyczące zwrotów, takie jak przyczyny podawane przez klientów. Te eksporty są opcjonalne.
* Folder `misc` może zawierać różne pliki. Jeśli chcesz używać tego folderu, omów z nami wcześniej hierarchię i strukturę, aby zapewnić kompatybilność.

Każdy eksport powinien być umieszczony w odpowiednim folderze i **opatrzony datą** przy użyciu nazwy pliku z sygnaturą czasową.

### Przykładowy format nazwy pliku

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

***

## 4. Wymagania dotyczące zawartości eksportu

Szczegółowa specyfikacja oczekiwanych pól, formatów i ograniczeń dla każdego typu zestawu danych jest dostępna w dokumentacji **Transfery danych: Szablon**.

**Kluczowe wymagania dotyczące eksportów katalogu produktów:**

* Eksportuj **wszystkie warianty produktów**, w tym artykuły niedostępne w magazynie
* Dołącz pole **daty ostatniej modyfikacji** do przetwarzania przyrostowego
* Zachowaj kompletne informacje o wariantach, aby umożliwić właściwą analizę rozmiarów
* Opcjonalnie dodaj flagę dezaktywacji do kontroli obecności Kleep

Zapoznaj się z szablonem, aby uzyskać wyczerpujące definicje pól i przykłady.

***

## 5. Obsługa powtarzających się danych w eksportach

Rekordy mogą zasadnie pojawiać się w wielu codziennych eksportach. Na przykład dany zwrot może być uwzględniony kilka razy w różnych plikach.

Nasz system ingestion automatycznie obsługuje deduplikację i przetwarza wyłącznie **najnowszą wersję** każdego rekordu.

***

## 6. Wytyczne dotyczące formatu danych

Wszystkie eksporty powinny być dostarczone w formacie **CSV**.

Pliki Excel (`.xlsx`) są odradzane, ponieważ wprowadzają niespójności formatowania i mogą komplikować automatyczne przepływy pracy ingestion.

* **Data i godzina:** Używaj formatu ISO 8601: `YYYY-MM-DDTHH:MM:SSZ` , przykład: `2025-01-15T14:30:00Z`
* **Kodowanie:** Kodowanie UTF-8 dla wszystkich pól tekstowych, właściwe escapowanie znaków specjalnych w CSV
* **Wartości logiczne:** Używaj `true`/`false` (małe litery) lub `True`/`False`
* **Wartości dziesiętne:** Używaj kropki (`.`) jako separatora dziesiętnego. Przykład: `129.99`, nie `129,99`
* **Wartości null:** Pusty ciąg znaków dla brakujących opcjonalnych pól tekstowych w CSV, użyj null w JSON

### Konwencja nazewnictwa plików

***

Zgodnie z dokumentacją struktury danych SFTP, używaj następującego formatu:

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

Przykłady:

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

***

## 7. Eksportowanie danych historycznych

Jeśli musisz dostarczyć **dane historyczne** (tj. dane niebędące częścią codziennych eksportów), możesz wyeksportować do **jednego roku historycznych rekordów** dla wszystkich typów danych, w tym:

* **Produktów**
* **Zamówień**
* **Zwrotów**

Historyczne zestawy danych można przesłać **przez SFTP** lub, jeśli jest to wygodniejsze, **za pośrednictwem innego uzgodnionego medium**.

# Przykład kompletnej struktury SFTP

```
/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  (opcjonalnie)
        /misc
            (opcjonalnie, omów hierarchię z nami)

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

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

```

***