🏢 Moduł Kontrahenci¶

Moduł Kontrahenci umożliwia zarządzanie bazą kontrahentów z zaawansowaną weryfikacją VAT, automatycznym wypełnianiem danych i oceną ryzyka kredytowego.

🎯 Główne funkcje¶

Zarządzanie kontrahentami¶

Pełny CRUD - Dodawanie, edycja, usuwanie kontrahentów
Wyszukiwanie na żywo - HTMX search z debounce 500ms
Sortowanie - Po nazwie, NIP, dacie dodania, statusie VAT
Filtry - Status, poziom ryzyka, grupa, klient
Widoki - Lista i karty (grid view)

Automatyczne wypełnianie danych¶

REGON API - Automatyczne pobieranie danych z GUS
Live NIP verification - Weryfikacja w czasie rzeczywistym podczas wprowadzania
Auto short name - Automatyczne generowanie skróconej nazwy (5 wzorców)
Strukturalny adres - Ulica, numer budynku, numer lokalu

Weryfikacja VAT¶

Biała Lista VAT - Automatyczna weryfikacja (API MF)
Status VAT - ACTIVE, REMOVED, EXEMPT, ERROR
Weryfikacja kont bankowych - Sprawdzanie każdego konta osobno
Automatyczne sprawdzanie - Codzienne weryfikacje o 6:00
Powiadomienia - Email gdy kontrahent zostanie usunięty z listy

Ocena ryzyka kredytowego¶

Auto-scoring - Automatyczna ocena 0-100 (5 czynników)
Poziomy ryzyka - LOW, MEDIUM, HIGH, CRITICAL
Limity kredytowe - Ustawianie limitów per kontrahent
Auto-block - Automatyczne blokowanie przy przekroczeniu limitu
Rekomendacje - Sugestie dotyczące limitów

Integracja z KSeF¶

KSeF identifier - Generowanie identyfikatorów KSeF
Weryfikacja - Sprawdzanie poprawności identyfikatorów
Strukturalny adres - Format wymagany przez KSeF
Submit to KSeF - Gotowe do integracji (stub)

📋 Struktura danych kontrahenta¶

Podstawowe informacje¶

Nazwa - Pełna nazwa kontrahenta
NIP - Numer Identyfikacji Podatkowej
REGON - Numer w rejestrze REGON
KRS - Numer w KRS (jeśli dotyczy)
Skrócona nazwa - Automatycznie generowana lub ręczna
Status - Aktywny, zarchiwizowany, zablokowany, usunięty

Adres¶

Ulica - Nazwa ulicy
Numer budynku - Numer budynku
Numer lokalu - Numer lokalu/mieszkania
Miasto - Miasto
Kod pocztowy - Kod pocztowy
Kraj - Domyślnie Polska

Dane VAT¶

Status VAT - ACTIVE, REMOVED, EXEMPT, ERROR
Data weryfikacji - Ostatnia data sprawdzenia
Konta bankowe - Lista zweryfikowanych kont
Ostatnia zmiana - Data ostatniej zmiany statusu

Ocena ryzyka¶

Score - 0-100 (automatycznie obliczany)
Poziom ryzyka - LOW, MEDIUM, HIGH, CRITICAL
Limit kredytowy - Maksymalna kwota
Zaległości - Suma zaległych płatności
Historia płatności - Analiza terminowości

Grupy i tagi¶

Grupa - Przypisanie do grupy (VIP, Export, B2B, itp.)
Tagi - JSON array z tagami
Kolor - Kolor grupy (dla UI)
Ikona - Ikona grupy

Relacja z klientem¶

Klient - Opcjonalne powiązanie z klientem CRM
Kontrahent biura - Checkbox dla kontrahentów biura (is_own_contractor)
Duplikaty - Sprawdzanie duplikatów per klient lub per team

🔗 Integracje¶

REGON API¶

Auto-fill - Automatyczne wypełnianie danych z REGON
Cache - 24h TTL w Redis
Retry - Automatyczne ponawianie przy błędach
Full SOAP API - Pełna integracja z API GUS

Biała Lista VAT (API MF)¶

Daily sync - Codzienne sprawdzanie o 6:00
Per account - Weryfikacja każdego konta bankowego
Status tracking - Śledzenie zmian statusu
Notifications - Powiadomienia o zmianach

KSeF (Krajowy System e-Faktur)¶

Identifier generation - Generowanie identyfikatorów
Validation - Walidacja przed wysłaniem
FA_VAT format - Format wymagany przez KSeF
Submit stub - Gotowe do implementacji

OCR/Saldeo/Scanye¶

Bi-directional sync - Dwukierunkowa synchronizacja
Auto-create - Automatyczne tworzenie z faktur
External IDs - Śledzenie ID z zewnętrznych systemów
Last sync - Timestamp ostatniej synchronizacji

📊 Dashboard kontrahentów¶

Statystyki¶

Wszystkich kontrahentów - Łączna liczba
Aktywnych - Kontrahenci aktywni
Z weryfikacją VAT - Zweryfikowani na Białej Liście
Z wysokim ryzykiem - Score > 70
Zaległości - Suma zaległych płatności

Ostrzeżenia¶

Usunięci z VAT - Kontrahenci usunięci z Białej Listy
Przekroczone limity - Przekroczone limity kredytowe
Dokumenty wygasające - Dokumenty z datą wygaśnięcia < 30 dni
Brak weryfikacji - Kontrahenci bez weryfikacji VAT

Ostatnia aktywność¶

Nowi kontrahenci - 5 najnowszych
Ostatnie weryfikacje - Ostatnie sprawdzenia VAT
Zmiany statusu - Ostatnie zmiany statusu

🚀 Jak używać¶

Dodawanie nowego kontrahenta¶

Przejdź do Kontrahenci → Dodaj kontrahenta
Wprowadź NIP - System automatycznie:
Sprawdzi NIP w REGON
Pobierze dane z GUS
Zweryfikuje na Białej Liście VAT
Sprawdź i uzupełnij dane
Wybierz klienta (jeśli kontrahent należy do klienta)
Lub zaznacz Kontrahent biura
Zapisz kontrahenta

Weryfikacja VAT¶

Przejdź do szczegółów kontrahenta
W sekcji Weryfikacja VAT zobaczysz:
Status na Białej Liście VAT
Zweryfikowane konta bankowe
Datę ostatniej weryfikacji
Kliknij Zweryfikuj teraz dla ręcznej weryfikacji
System automatycznie sprawdzi codziennie o 6:00

Ocena ryzyka¶

System automatycznie oblicza score (0-100) na podstawie:
40% - Historia płatności
30% - Zaległe kwoty
15% - Status VAT
10% - Długość współpracy
5% - Wielkość firmy
Poziom ryzyka jest automatycznie przypisywany:
LOW (0-40) - Zielony
MEDIUM (41-60) - Żółty
HIGH (61-80) - Pomarańczowy
CRITICAL (81-100) - Czerwony
Ustaw limit kredytowy dla kontrahenta
System automatycznie zablokuje przy przekroczeniu

Grupy kontrahentów¶

Utwórz grupę (np. "VIP", "Export", "B2B")
Przypisz kontrahentów do grupy
Ustaw domyślne warunki dla grupy
Użyj kolorów i ikon dla łatwej identyfikacji

💡 Najlepsze praktyki¶

Organizacja kontrahentów¶

Grupy - Używaj grup do kategoryzacji
Tagi - Dodawaj tagi dla łatwego wyszukiwania
Statusy - Używaj statusów do zarządzania
Notatki - Dodawaj ważne informacje

Weryfikacja¶

Regularne sprawdzanie - System sprawdza codziennie
Monitorowanie zmian - Sprawdzaj powiadomienia o zmianach statusu
Konta bankowe - Weryfikuj każde konto osobno
Dokumenty - Przechowuj ważne dokumenty

Zarządzanie ryzykiem¶

Limity - Ustawiaj limity kredytowe
Monitoring - Monitoruj score i poziom ryzyka
Auto-block - Włącz automatyczne blokowanie
Rekomendacje - Używaj sugestii systemu

🔧 Zaawansowane funkcje¶

Kontakty¶

Każdy kontrahent może mieć wiele kontaktów: - Rola - Główny, finansowy, techniczny - Email - Adres email - Telefon - Numer telefonu - Stanowisko - Stanowisko w firmie - Dział - Dział w firmie

Konta bankowe¶

Wiele kont - Każdy kontrahent może mieć wiele kont
Weryfikacja VAT - Każde konto jest weryfikowane osobno
Konto domyślne - Ustaw domyślne konto
Auto-fill - Automatyczne wypełnianie z Master Data (Bank FK)
Statystyki - Śledzenie użycia (last_used_at, usage_count)

Dokumenty¶

Typy dokumentów - Umowy, certyfikaty, pełnomocnictwa
Data ważności - Śledzenie dat wygaśnięcia
Powiadomienia - Automatyczne powiadomienia 30 dni przed wygaśnięciem
Wersjonowanie - Historia zmian

Timeline aktywności¶

Pełna historia zmian: - 18 typów aktywności - Utworzenie, edycja, weryfikacja, itp. - JSON diff - Śledzenie zmian w danych - IP address - Logowanie adresów IP - User tracking - Kto wykonał akcję - Auto-logging - Automatyczne przez signals

📈 Przewaga konkurencyjna¶

Moduł Kontrahenci oferuje funkcje, których nie ma konkurencja:

✅ VAT auto-verify daily (+18 miesięcy)
✅ REGON auto-fill (+12 miesięcy)
✅ KSeF full integration (+6 miesięcy)
✅ Credit risk scoring (+24 miesiące)
✅ Bank accounts VAT check (+18 miesięcy)
✅ OCR/Saldeo/Scanye sync (+12 miesięcy)
✅ Activity timeline (+12 miesięcy)
✅ Document expiry alerts (+12 miesięcy)

TOTAL: 18-24 miesiące przewagi! 🏆

📚 Więcej informacji¶

Ostatnia aktualizacja: 2025-11-29
Wersja modułu: 1.0