KCDRS
Instrukcja przygotowania KCFirmy, konfiguracji robota i automatycznej kontroli opakowań kaucyjnych.
Do czego służy KCDRS
KCDRS wspomaga obsługę opakowań kaucyjnych w KCFirma. Program może reagować na nowo utworzone lub zmodyfikowane kartoteki towarowe, sprawdzać wymagane opakowanie i automatycznie doprowadzać przypisanie w bazie do właściwego stanu.
Automatyczna korekta
Po zmianie kartoteki robot może dodać brakujące opakowanie, usunąć opakowanie, którego być nie powinno, albo zmienić błędne przypisanie.
Zwrotka.com
Najpewniejszy wariant wykorzystuje API Zwrotka.com do ustalenia frakcji opakowania na podstawie kodu EAN.
Raport zgodności
Można hurtowo sprawdzić istniejące towary w wybranej grupie i otrzymać raport HTML bez modyfikowania kartotek.
Trzy funkcje programu — nie należy ich mylić
1. Praca bieżąca — lokalna
Nowy lub zmodyfikowany towar trafia do mechanizmu „Towary dla DRS”. KCDRS ustala opakowanie na podstawie skonfigurowanej pary grupa towarowa → opakowanie.
2. Praca bieżąca — API
Po pojawieniu się informacji o zmianie kartoteki KCDRS sprawdza EAN w Zwrotka.com i na tej podstawie dodaje, usuwa albo zmienia opakowanie w KCFirma.
3. Raport hurtowy
Wybrana grupa jest sprawdzana towar po towarze w API Zwrotka.com. Ta funkcja niczego nie zmienia w bazie. Wynik trafia do raportu HTML.
Wymagania
- program KCFirma i dostęp do jej bazy
.danlub.mdb, - 32-bitowy sterownik Microsoft Access/ACE zgodny z aplikacją Win32,
- prawo odczytu i zapisu bazy oraz katalogu programu KCDRS,
- wspólny katalog wymiany dostępny zarówno dla KCSerwera, jak i KCDRS,
- dla trybu API: aktywna usługa Zwrotka.com, połączenie z Internetem oraz ID/Secret przekazane przez firmę Zwrotka lub dostępne w panelu
market.ezwrotka.com, - dla silnika Indy: dołączone do archiwum biblioteki OpenSSL obok programu.
Utwórz towary reprezentujące opakowania kaucyjne
Przed konfiguracją robota w KCFirma muszą istnieć towary reprezentujące opakowania, które KCDRS będzie przypisywał do produktów. Dla typowego wdrożenia należy przygotować co najmniej trzy pozycje odpowiadające podstawowym frakcjom:
- Butelka PET kaucja — opakowania z tworzywa,
- Puszka kaucja — opakowania metalowe,
- Butelka szkło kaucja — opakowania szklane.
Nazwy są przykładowe. Istotne jest, aby pozycje istniały w kartotece i można było je jednoznacznie wskazać w konfiguracji KCDRS.
Utwórz w KCFirma mechanizm „Towary dla DRS”
KCFirma nie udostępnia KCDRS znacznika czasowego informującego, że kartoteka towarowa została właśnie utworzona lub zmieniona. Dlatego KCDRS wykorzystuje istniejący mechanizm eksportu danych dla etykiet elektronicznych / wag i sprawdzarek cen. Mechanizm ten tworzy pliki informujące o towarach, które wymagają ponownego przetworzenia.
- W KCFirma przejdź do Administracja → Konfiguracja → Sprzęt → Wagi i sprawdzarki cen.
- Utwórz nową konfigurację urządzenia, np. pod nazwą Towary dla DRS. Nazwę warto zapamiętać — pojawi się później w ustawieniach grup i w funkcji serwisowej KCDRS.
- Skonfiguruj urządzenie zgodnie z przykładem. Numer „WAGA” może być dowolnym wolnym numerem.
- Ustaw katalog wymiany, np.
D:\TowaryDlaDRS. Katalog musi być dostępny dla procesu KCSerwera oraz dla konta uruchamiającego KCDRS. - Ten sam katalog wskaż później w KCDRS jako Folder Plików Etykiet.
Włącz wysyłanie zmian dla odpowiednich grup towarowych
Aby utworzenie lub modyfikacja kartoteki skutkowała pojawieniem się informacji w folderze „Towary dla DRS”, odpowiednie grupy towarowe muszą mieć włączone utworzone urządzenie.
- Wejdź w Kartoteki → Grupy towarowe.
- Wybierz grupę i użyj funkcji Popraw.
- Przejdź do zakładki Wagi i sprawdzarki cen.
- Zaznacz urządzenie Towary dla DRS i zapisz grupę.
Skonfiguruj KCDRS
Większość ustawień jest wspólna dla obu trybów. Wskaż bazę KCFirma, interwał pracy i wybrany sposób komunikacji HTTP. Następnie skonfiguruj jeden z dwóch sposobów ustalania opakowania.
7.1. Tryb API Zwrotka.com — zalecany
W trybie API KCDRS odczytuje kody EAN z nowych plików utworzonych przez mechanizm KCFirma i pyta Zwrotka.com o właściwą frakcję opakowania. Następnie porównuje wynik z bieżącym stanem kartoteki.
KCFirma
import_*.csv
Zwrotka.com
KCFirma
W sekcji API Zwrotka.com należy połączyć frakcje zwracane przez usługę z przygotowanymi wcześniej towarami-opakowaniami. Przykładowo:
| Frakcja | Przykładowe opakowanie w KCFirma |
|---|---|
| Tworzywa sztuczne (PET) | Butelka PET kaucja |
| Metal (Puszka) | Puszka kaucja |
| Szkło | Butelka szkło kaucja |
7.2. Procedura lokalna
Procedura lokalna nie korzysta z Zwrotka.com. Administrator tworzy w KCDRS powiązania grupa towarowa → opakowanie. Towar z danej grupy otrzymuje skonfigurowane opakowanie.
API Zwrotka.com
- decyzja oparta na kodzie EAN i danych z usługi,
- znacznie mniejsze ryzyko błędnego przypisania,
- możliwość dodania, usunięcia lub zmiany opakowania,
- wymaga aktywnej usługi i danych API.
Procedura lokalna
- decyzja oparta wyłącznie na grupie towarowej,
- prosta i niezależna od Internetu,
- poprawność zależy od właściwego przypisania towarów do grup,
- zalecana tam, gdzie struktura grup jest jednoznaczna i dobrze utrzymana.
7.3. Silnik HTTP
KCDRS udostępnia dwa mechanizmy komunikacji z usługą Zwrotka.com:
System — TNetHTTPClient
Preferowany. Jest bardzo szybki i powinien być pierwszym wyborem na nowszych systemach. Jako bezpieczny punkt odniesienia przy wdrożeniu przyjmujemy Windows 10 / Windows Server 2016 i nowsze. Na starszym systemie można go po prostu przetestować — jeśli działa poprawnie, nie ma potrzeby przechodzenia na Indy.
Indy — OpenSSL
Wariant zgodności dla starszych środowisk. Działa wolniej, ale jest wystarczający do bieżącej pracy. Wymaga bibliotek libeay32.dll i ssleay32.dll dostarczonych w archiwum programu.
Co dzieje się po uruchomieniu robota
Po uruchomieniu KCDRS analizuje tylko towary, o których zmianie poinformował mechanizm „Towary dla DRS”. Dzięki temu nie skanuje bez potrzeby całej kartoteki przy każdym cyklu.
W trybie API
- KCDRS wykrywa nowy plik
import_*.csv. - Odczytuje EAN zmienionego towaru.
- Pyta Zwrotka.com o informację dotyczącą opakowania/frakcji.
- Porównuje wynik z opakowaniem zapisanym w KCFirma.
- Jeżeli opakowania brakuje — dodaje je.
- Jeżeli opakowanie jest błędne — zmienia je.
- Jeżeli towar nie powinien mieć opakowania, a ma je przypisane — usuwa je.
W trybie lokalnym
KCDRS korzysta z mapowania grup i na jego podstawie ustawia opakowanie właściwe dla grupy. Ponieważ metoda nie sprawdza EAN w zewnętrznym źródle, jej poprawność zależy od jakości struktury grup towarowych.
Funkcje serwisowe
Okno Serwis zawiera dwie niezależne funkcje: masową konfigurację urządzenia w grupach oraz hurtowy raport zgodności.
Aktualizacja urządzeń
Wybierz z listy urządzenie utworzone wcześniej w Wagi i sprawdzarki cen, np. „Towary dla DRS”, i kliknij Aktualizuj. KCDRS ustawi wskazane urządzenie jako aktywne we wszystkich grupach towarowych.
Hurtowy raport zgodności istniejących kartotek
Raport jest przeznaczony do sprawdzania towarów, które istniały w bazie przed wdrożeniem KCDRS albo których poprawność chcemy skontrolować ponownie.
- Otwórz Serwis.
- Wybierz grupę towarową do sprawdzenia.
- Kliknij Raport.
- KCDRS sprawdzi towary z EAN w API Zwrotka.com i porówna wynik z opakowaniem zapisanym w KCFirma.
- Po zakończeniu zapisze raport HTML w katalogu
raporty.
| Przykładowy wynik | Znaczenie |
|---|---|
| Zgodne | Przypisanie w KCFirma odpowiada danych z API. |
| Brak opakowania | API wskazuje kaucję, a kartoteka nie ma opakowania. |
| Błędne przypisanie | W kartotece wskazane jest inne opakowanie niż wynikające z API. |
| Nadmiarowe opakowanie | API nie wskazuje kaucji, a towar ma opakowanie. |
| Brak kodu paskowego | Brak EAN uniemożliwia sprawdzenie online. |
Bezpieczeństwo i dobre praktyki
- regularnie wykonuj kopie bazy KCFirma, szczególnie przed funkcjami serwisowymi,
- nie uruchamiaj wielu kopii KCDRS dla tej samej bazy i tego samego katalogu wymiany,
- ogranicz dostęp NTFS do katalogu programu — plik
KCDRS.inimoże zawierać ID i Secret API, - nie publikuj ani nie wysyłaj pliku INI wraz ze zgłoszeniami serwisowymi,
- po zmianie mapowań wykonaj kontrolny raport reprezentatywnej grupy,
- przy kopiowaniu bazy lub zmianach konfiguracyjnych zatrzymaj robota.
Najczęstsze problemy
| Objaw | Co sprawdzić |
|---|---|
| Brak połączenia z bazą | Ścieżkę do pliku, prawa użytkownika oraz obecność 32-bitowego silnika Access/ACE. |
| Nowe/zmienione towary nie są analizowane | Czy grupa ma zaznaczone urządzenie „Towary dla DRS”, czy KCSerwer tworzy pliki oraz czy KCDRS obserwuje ten sam folder. |
| Brak plików w folderze wymiany | Konfigurację urządzenia w KCFirma i zaznaczenie urządzenia w grupach towarowych. |
| Błąd API Zwrotka.com | ID, Secret, adresy usług, dostęp do Internetu i silnik HTTP. W razie problemu z trybem systemowym przetestuj Indy. |
| Indy nie łączy się z usługą | Czy obok EXE znajdują się właściwe biblioteki OpenSSL dostarczone z programem. |
| Raport trwa długo | To normalne dla dużej grupy — każdy towar z EAN wymaga osobnego zapytania do API. |
Checklista
KCFirma
- Utworzono towary-opakowania PET, metal i szkło.
- Utworzono urządzenie „Towary dla DRS”.
- Ustawiono katalog wymiany dostępny dla KCSerwera i KCDRS.
- Urządzenie zaznaczono w wymaganych grupach albo wykonano masową aktualizację z KCDRS.
KCDRS
- Wskazano poprawną bazę KCFirma.
- Wybrano tryb API lub procedurę lokalną.
- W trybie API wpisano właściwe dane Zwrotka.com.
- Zdefiniowano mapowania frakcji lub grup.
- Folder plików etykiet wskazuje katalog skonfigurowany w KCFirma.
- Wykonano próbę na kilku kartotekach i sprawdzono wynik w bazie.
- Wykonano raport kontrolny dla przykładowej grupy.