KCRobot — instrukcja użytkownika

1. Do czego służy KCRobot

KCRobot cyklicznie analizuje kontrahentów zapisanych w bazie KCFirma. Sprawdza NIP, pobiera dane z CEIDG lub GUS, porównuje je z kartoteką i zapisuje wynik w bazie.

Walidacja NIP

Numer jest normalizowany i sprawdzany lokalnie przed zapytaniem do Internetu.

CEIDG i GUS

Program korzysta z obu rejestrów, dobierając źródło do rodzaju i dostępności danych.

Aktualizacja kartoteki

Może zaktualizować nazwę, ulicę, numer, kod pocztowy i miejscowość.

Raport zmian

Po cyklu powstaje raport z operacji i sytuacji wymagających uwagi.

2. Wymagania

Windows; aplikacja jest kompilowana jako Win32.
Windows Server 2012 R2 lub nowsze środowisko Windows.
Baza KCFirma Microsoft Access 2000 w pliku .mdb lub .dan.
32-bitowy silnik Microsoft Access zgodny z aplikacją.
Dostęp do Internetu i połączenia HTTPS z obsługą TLS 1.2.
Własny token CEIDG oraz własny klucz GUS BIR.
Prawo odczytu i zapisu do bazy oraz katalogu programu.

Przed pierwszym użyciemWykonaj kopię zapasową bazy KCFirma. Program aktualizuje rekordy kartoteki kontrahentów.

3. Pierwsze uruchomienie

Rozpakuj KCRobot do docelowego katalogu.
Uruchom KCRobot.exe.
Wskaż plik bazy KCFirma, jeśli program nie ma jeszcze skonfigurowanej ścieżki.
Otwórz Konfiguracja i ustaw parametry pracy.
W zakładce API wpisz własny token CEIDG i klucz GUS.
Zapisz ustawienia i włącz robota głównym przełącznikiem.

4. Konfiguracja

Ogólne

Opcja	Znaczenie
Interwał pracy robota	Czas oczekiwania pomiędzy pełnymi cyklami skanowania.
Automatycznie włącz robota	Uruchamia pracę od razu po starcie programu.
Uruchamiaj w zasobniku	Program startuje bez otwierania głównego okna.
Pomijaj dostawców	Robot sprawdza tylko odbiorców.

Baza danych

Wskaż właściwy plik bazy KCFirma. Po zapisaniu program sprawdza, czy połączenie może zostać nawiązane.

API

Wpisz token CEIDG oraz klucz GUS. Pola są maskowane w oknie konfiguracji.

Zmiana ustawieńKonfigurację zmieniaj po zatrzymaniu robota. Nowe wartości zostaną użyte przy następnym uruchomieniu wątku.

5. Codzienna praca

Po włączeniu robot pobiera kolejne nieprzetworzone rekordy z NIP i wykonuje następujący cykl:

oczyszcza i sprawdza NIP,
odpytuje CEIDG,
w razie potrzeby odpytuje GUS,
porównuje nazwę i adres z danymi KCFirma,
zapisuje korekty w transakcji,
ustawia status i źródło danych,
dopisuje zdarzenie do raportu lub logu.

Program może pozostać w zasobniku systemowym. Zamknięcie głównego okna krzyżykiem nie kończy robota — użyj przycisku Zakończ lub polecenia z menu ikony przy zegarze.

6. Statusy i raporty

Status	Znaczenie
OK	NIP poprawny, dane znaleziono i porównano. Status pozostaje OK także po aktualizacji danych.
WARN	Sytuacja wymagająca uwagi, np. brak danych online lub wiele wpisów.
ERR	Błędny NIP albo błąd komunikacji/przetwarzania.

Raporty HTML są zapisywane w podfolderze Raporty. Dodatkowy log techniczny znajduje się obok programu w pliku KCRobot_Raport.txt.

7. Funkcje serwisowe

UwagaOperacje serwisowe zmieniają wiele rekordów. Przed ich użyciem wykonaj kopię bazy i zatrzymaj robota.

Funkcja	Działanie
ResetAPI	Przygotowuje przetworzone rekordy do ponownego pobrania danych online, z wyjątkiem trwałych błędów NIP.
ResetAll	Czyści stan techniczny wszystkich kontrahentów i uruchamia pełną weryfikację od początku.
ResetCEIDG	Przygotowuje do ponownego sprawdzenia rekordy wcześniej zweryfikowane przez CEIDG.

8. Bezpieczeństwo

Przed pierwszym uruchomieniem i funkcjami serwisowymi wykonuj kopię bazy.
Nie uruchamiaj kilku instancji KCRobot na tej samej bazie.
Do CEIDG i GUS program komunikuje się przez HTTPS i wymaga TLS 1.2.
Token CEIDG i klucz GUS są maskowane w GUI, ale w pliku KCRobot.ini są zapisane jako zwykły tekst.
Ogranicz prawa do katalogu programu do zaufanych kont Windows.
Nie przesyłaj kluczy API w raportach ani zgłoszeniach serwisowych.

9. Rozwiązywanie problemów

Objaw	Co sprawdzić
Brak połączenia z bazą	Ścieżkę pliku, prawa użytkownika i 32-bitowy silnik Access.
Błąd API	Klucze, dostęp do Internetu, TLS 1.2, zaporę oraz log techniczny.
Nie można otworzyć konfiguracji	Najpierw zatrzymaj robota i poczekaj na zakończenie wątku.
Rekord nie jest ponownie sprawdzany	Użyj odpowiedniej funkcji serwisowej po wykonaniu kopii bazy.
Okno zniknęło	Program prawdopodobnie działa w zasobniku systemowym.