Przejdź do głównej treści

​
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