Instrukcja Instalacji Integrator SYSTIM – BASELINKER API

1. Wymagania techniczne

Żeby INTEGRATOR działał poprawnie, serwer musi spełniać:

• PHP 8.1–8.3 (zalecane 8.3)
  • włączone: curl, mbstring, json, pdo_mysql, openssl
• MariaDB / MySQL 5.7+ (zalecane MariaDB 10.6+)
• Dostęp:
  • HTTP(S) do katalogu /invbasesystim/
  • SSH (do uruchomienia composer i crona)
• Composer (globalnie lub w katalogu projektu)
• Możliwość ustawienia CRON (np. w panelu DirectAdmin lub przez crontab -e)
• Działający serwer SMTP (do wysyłki powiadomień – TLS/SSL)

2. Struktura i umiejscowienie plików

INTEGRATOR zakładamy w katalogu:

/domains/TWOJA-DOMENA/public_html/invbasesystim/

Adres panelu:
https://TWOJA-DOMENA/invbasesystim/

W katalogu powinny znaleźć się m.in.:

• index.php – panel WWW (login, konfiguracja, logi, ręczne akcje)
• cron.php – skrypt uruchamiany z CRON-a
• katalog app/ – logika (Services, Repositories, itp.)
• katalog storage/ – tu lecą pliki PDF faktur z Systim (storage/invoices/...)
• vendor/ – zależności Composera
• pliki SQL z tabelami (jeśli dostarczasz .sql do importu)

3. Instalacja krok po kroku

3.1. Wgranie plików

1. Rozpakuj paczkę INTEGRATOR lokalnie.
2. Skopiuj zawartość do katalogu na serwerze:
   • .../public_html/invbasesystim/
3. Upewnij się, że katalogi:
   • storage/
   • storage/invoices/
     mają prawo zapisu dla PHP (np. 755 albo 775 zależnie od serwera).

3.2. Composer (zależności PHP)

W katalogu /invbasesystim/:

cd ~/domains/TWOJA-DOMENA/public_html/invbasesystim
composer install --no-dev -o

Po tym w katalogu pojawi się /vendor.

3.3. Baza danych

1. Utwórz nową bazę danych w DirectAdmin (np. integrator_db).
2. Utwórz użytkownika i nadaj mu pełne uprawnienia do tej bazy.
3. Zaimportuj dostarczony plik SQL (np. admin_invbasesystim.sql + struktura tabel):
   • przez phpMyAdmin / mysql -u USER -p DB_NAME < plik.sql

W bazie powinny się pojawić m.in. tabele:

• users – administratorzy panelu
• settings – konfiguracja (API, SMTP, opcje automatyzacji)
• logs – logi systemowe
• contractors – cache kontrahentów z Systim
• orders – zamówienia z BaseLinker + powiązanie z Systim

3.4. Połączenie z bazą (Database.php)

W pliku app/Core/Database.php (albo odpowiedniku, który już masz) uzupełniasz dane:

• host (np. localhost)
• nazwa bazy
• login i hasło DB

Jeżeli to już ustawione i działa (panel się ładuje i logi zapisują), tego punktu nie ruszasz.

4. Utworzenie konta administratora

Żeby wejść do panelu, trzeba mieć konto admina.

Masz jednorazowy skrypt do tworzenia admina (np. create_admin.php, który wcześniej generowaliśmy).
Procedura:

1. Skopiuj plik create_admin.php do katalogu /invbasesystim/.
2. Wejdź w przeglądarce na:
   https://TWOJA-DOMENA/invbasesystim/create_admin.php
3. Wypełnij formularz:
   • E-mail administratora (będzie loginem)
   • Hasło (silne, min. 12 znaków)
4. Zapisz.
5. Usuń plik create_admin.php z serwera (żeby nikt z zewnątrz nie utworzył swojego admina).

Od teraz logujesz się na:
https://TWOJA-DOMENA/invbasesystim/
danymi e-mail + hasło ustawionymi wyżej.

5. Konfiguracja w panelu INTEGRATOR

Po zalogowaniu przejdź do zakładki Konfiguracja.

5.1. BaseLinker

Sekcja BaseLinker:

• API token (X-BLToken)
  → wklejasz klucz API wygenerowany w panelu BaseLinker (base.com).
  Ten sam klucz wykorzystujemy jako wartość nagłówka X-BLToken.
• Data początkowa (od kiedy pobierać zamówienia)
  → format YYYY-MM-DDTHH:MM (pole typu datetime-local).
  INTEGRATOR pobiera wyłącznie zamówienia od tej daty wzwyż.
  Zamówienia starsze są ignorowane.

Opcjonalnie (jeśli w skrypcie jest pole) – ID serii faktur w BaseLinker:

• to jest tzw. series_id (identyfikator serii numeracji faktur) – odczytasz go w panelu BaseLinker.
• jeśli to pole istnieje w ustawieniach – wpisujesz tam dokładnie ten numer, którego BaseLinker oczekuje dla metody addInvoice.

5.2. Systim

Sekcja Systim:

• URL API (jsonAPI.php)
  Przykład:
  https://twojafirma.systim.pl/jsonAPI.php
• Login użytkownika API (Systim)
  → login dedykowanego użytkownika Systim, np. integrator_api.
  Użytkownik powinien mieć uprawnienia min. do:
  • odczytu/edycji kontrahentów
  • wystawiania faktur
  • (opcjonalnie) księgowania wpłat
• Hasło API (z zakładki użytkownicy)
  → hasło zdefiniowane dla tego użytkownika w Systim (pole „hasło API”).

API Systim działa u nas na parametrach:

• act=... – nazwa operacji
• token – token uzyskany po login
• login robimy przez: act=login, login=, haslo=

Użytkownik w Systim może być np. typu „Fakturzysta”, żeby nie miał pełnego admina.

5.3. Automaty (logika integracji)

Sekcja Automaty:

• Automatyczne wystawianie faktur w Systim
  • gdy zaznaczone: integrator przy CRON:
    • pobiera zamówienia z BaseLinker
    • dopasowuje / tworzy kontrahentów w Systim
    • wystawia fakturę VAT w Systim
    • pobiera PDF faktury
    • wysyła PDF do BaseLinker (zamienia ich „bezwartościową” fakturę)
• Automatyczne księgowanie płatności (dla zamówień opłaconych)
  • gdy zaznaczone: po wykryciu, że zamówienie w BaseLinker ma status zapłacone,
    INTEGRATOR:
    • wystawia fakturę w Systim (jeśli nie wystawiona)
    • księguje wpłatę (metoda addPayment w Systim)
  • gdy wyłączone: faktury są wystawiane, ale wpłaty trzeba księgować ręcznie w Systim.

5.4. Powiadomienia / SMTP

Sekcja Powiadomienia / SMTP:

• Adres e-mail powiadomień
  → na ten adres przychodzą:
  • informacje o testach połączenia
  • błędy integracji
  • raporty z generowania faktur
• SMTP host – np. h69.seohost.pl
• SMTP port – np. 587 (TLS) albo 465 (SSL)
• SMTP użytkownik – pełny login, np. powiadomienia@poczta.qssl.pl
• SMTP hasło – hasło do skrzynki
• Szyfrowanie (ssl/tls) – wpisujesz tls albo ssl zgodnie z tym, jak działa serwer

Wysyłka jest realizowana wyłącznie przez Symfony Mailer (Composer), nie lokalne mail().

6. Testy połączeń

Po zapisaniu konfiguracji:

1. W zakładce Konfiguracja kliknij:
   • Przetestuj połączenia

Efekty:

• w panelu pojawi się info „Test połączeń został wykonany. Sprawdź email/logi.”
• w logach (Logi w menu) zobaczysz wpis:
  • źródło admin: Connections tested
  • źródło baselinker: wynik testu
  • źródło systim: Test connection failed albo przejście testu
• na mailu powiadomienia: raport z testu (BaseLinker OK/BŁĄD, Systim OK/BŁĄD)

Jeżeli BaseLinker i Systim są OK → można iść dalej.

7. Kontrahenci – cache z Systim

W zakładce Konfiguracja masz przycisk:

• Odśwież kontrahentów z Systim

Po kliknięciu:

• INTEGRATOR:
  • loguje się do Systim,
  • pobiera listę kontrahentów (listCompanies),
  • czyści tabelę contractors,
  • zapisuje komplet aktualnych kontrahentów (oznaczając typ: firma/osoba).

Po wykonaniu:

• w panelu zobaczysz komunikat „Odświeżono kontrahentów z Systim (X rekordów)”
• w logach:
  • contractors → Starting contractors refresh from Systim
  • contractors → Contractors refresh finished z liczbą rekordów

To jest fundament do dalszego matchowania zamówień z BL ↔ kontrahenci Systim.

8. Import zamówień z BaseLinker

Masz dwie opcje:

8.1. Test ręczny z panelu

W zakładce Dashboard:

• przycisk Przetestuj pobieranie zamówień z BaseLinker

To:

• bierze datę początkową z ustawień (baselinker_date_start),
• wywołuje w tle getOrdersSince(...),
• zapisuje wynik w logach,
• wysyła maila z info, ile zamówień pobrano.

8.2. Ręczny import + generowanie faktur

Jeżeli w panelu masz osobny przycisk typu:

• Importuj zamówienia z BaseLinker
• Wystaw faktury Systim i wyślij do BaseLinker

to kolejno:

1. Import → do tabeli orders trafiają zamówienia z BL:
   • dane nabywcy (osoba / firma)
   • adres, NIP, kwoty netto/brutto/VAT
   • status zamówienia
2. Przy generowaniu faktur:
   • dla każdego zamówienia bez powiązania:
     • próba dopasowania kontrahenta po:
       • firma: NIP
       • osoba prywatna: imię + nazwisko + adres (ulica, kod, miasto)
     • jeśli nie znajdzie kontrahenta:
       • tworzy kontrahenta w Systim (addCompany)
       • odświeża cache kontrahentów lokalnie
       • ponownie przypisuje ID kontrahenta do zamówienia
     • wystawia fakturę w Systim (addSellInvoice)
     • pobiera PDF (getSellInvoicePdf)
     • zapisuje PDF na serwerze (np. storage/invoices/ID_NUMER.pdf)
     • wysyła PDF do BaseLinker:
       • jeśli w BL brak faktury – najpierw addInvoice
       • potem addOrderInvoiceFile z base64(faktury z Systim)
     • oznacza zamówienie w tabeli:
       • systim_invoice_id
       • systim_invoice_number
       • invoice_pdf_path
       • invoice_sent_to_bl = 1

9. Automatyzacja CRON

Żeby całość działała automatycznie, ustawiasz CRON tak, by uruchamiał cron.php.

9.1. Ręczne odpalenie (test)

Na SSH:

cd ~/domains/TWOJA-DOMENA/public_html/invbasesystim
php cron.php

Typowy output:

[2025-11-21 19:36:59] == Import orders ==
[2025-11-21 19:36:59] Imported orders: X
[2025-11-21 19:36:59] == Generate invoices ==
[2025-11-21 19:37:01] Invoices total: Y, OK: A, failed: B
[2025-11-21 19:37:01] == DONE ==

W tym czasie:

• nowe zamówienia z BaseLinker są pobierane,
• brakujący kontrahenci są tworzeni w Systim,
• faktury są wystawiane i wysyłane do BaseLinker,
• błędy lecą w logi + na e-mail powiadomień.

9.2. CRON w systemie

Przykład crontaba (co 5 minut):

*/5 * * * * /usr/bin/php -q /home/admin/domains/TWOJA-DOMENA/public_html/invbasesystim/cron.php >> /home/admin/cron_invbasesystim.log 2>&1

Dostosuj:

• ścieżkę do php (/usr/bin/php albo /usr/local/bin/php)
• ścieżkę do katalogu
• częstotliwość (np. co 10 min, co 15 min)

10. Podsumowanie – co użytkownik musi wpisać i gdzie

1. Pliki – wgrać do /invbasesystim/.
2. Composer – composer install w katalogu projektu.
3. Baza danych:
   • utworzyć DB + user,
   • zaimportować dostarczone .sql,
   • ustawić dane połączenia w pliku Database.php (jeśli nie są wpisane).
4. Admin:
   • odpalić jednorazowy skrypt tworzący konto admina,
   • usunąć ten skrypt.
5. Konfiguracja w panelu → Konfiguracja:
   • BaseLinker:
     • API token (X-BLToken)
     • data początkowa
     • (opcjonalnie) ID serii faktur
   • Systim:
     • URL API (jsonAPI.php)
     • login użytkownika API
     • hasło API
   • Automaty:
     • włączyć / wyłączyć automatyczne wystawianie faktur
     • włączyć / wyłączyć automatyczne księgowanie płatności
   • Powiadomienia / SMTP:
     • adres maila powiadomień
     • SMTP host/port/użytkownik/hasło/szyfrowanie
6. Testy:
   • Przetestuj połączenia
   • Odśwież kontrahentów
   • testowy import zamówień z BL i ręczne wystawienie faktur z panelu
7. CRON:
   • ustawić zadanie systemowe php cron.php co X minut.