# Integracje

# Comarch Optima

# Integracja THTG Integrator z Comarch Optima

## Słownik

- **Integrator** – system **THTG Integrator**
- **Optima** – system księgowy **Comarch ERP Optima**
- **ThtgEsb** – aplikacja integrująca **Integrator** z **Optimą**

---

# Wstęp

Integrator posiada aplikację integracyjną o nazwie **ThtgEsb**, która umożliwia komunikację z systemem **Comarch ERP Optima**.

Do wymiany danych wykorzystywana jest **szyna danych**, dzięki czemu serwer z Optimą **nie musi być dostępny z zewnątrz**.  
Aplikacja **ThtgEsb** musi jednak posiadać **dostęp do internetu**, aby komunikować się z szyną danych.

ThtgEsb loguje się do Optimy wykorzystując **dostępną licencję użytkownika**.

Jeżeli liczba dostępnych licencji jest niewystarczająca:

- ThtgEsb nie będzie mogła zalogować się do Optimy
- dane nie zostaną wysłane
- aplikacja będzie ponawiała próbę logowania aż do zwolnienia licencji

⚠️ **Uwaga**

Optima **nie zwalnia automatycznie licencji przy bezczynności użytkownika**.  
Licencja zostanie zwolniona dopiero po:

- zamknięciu programu Optima
- wylogowaniu użytkownika z systemu Windows

Jeżeli zależy nam na wysokiej niezawodności komunikacji, zaleca się **wykupienie osobnej licencji dla ThtgEsb**.

---

# Wymagania

Do uruchomienia integracji wymagane są:

- dostęp do serwera, na którym znajduje się **Optima**, w celu instalacji **ThtgEsb**
- dane logowania użytkownika (login i hasło)
- lista baz danych, z którymi aplikacja będzie się łączyła
- **testowa wersja bazy danych firmy**, aby przeprowadzić testy integracji przed uruchomieniem produkcyjnym

⚠️ **Uwaga**  
Integracja **nie współpracuje z wersją chmurową Comarch ERP Optima**.

---

# Możliwości integracji

Aplikacja **ThtgEsb** pozwala na integrację w następujących obszarach.

---

# Tworzenie kontrahentów (Integrator → Optima)

Po utworzeniu kontrahenta w **Integratorze** zostaje on automatycznie wysłany do **Optimy**.

Kontrahenci są wysyłani:

- po utworzeniu lub modyfikacji w sekcji **Klient → Kontrahent**
- po utworzeniu i podpisaniu **umowy dla klienta**

Jeżeli umowa zawierana jest dla **kilku klientów**, w Optimie tworzony jest **jeden kontrahent zawierający dane wszystkich klientów**.

Przed wysłaniem kontrahenta Integrator sprawdza, czy istnieje on już w Optimie.

Weryfikacja odbywa się na podstawie:

- **NIP**
- **PESEL**

Jeżeli kontrahent nie zostanie odnaleziony, Integrator utworzy go automatycznie.

### Zasada tworzenia kodów kontrahentów

- klienci: `K_{id klienta}`
- kontrahenci: `KT_{id kontrahenta}`

Przykłady:

- `K_3123`
- `KT_3121`

⚠️ **Uwaga**

Kontrahenci muszą posiadać **uzupełniony NIP lub PESEL**, aby uniknąć tworzenia duplikatów.

---

# Import kontrahentów (Optima → Integrator)

Funkcjonalność umożliwia import kontrahentów z Optimy do Integratora.

*(sekcja w trakcie zmian)*

---

# Tworzenie faktur kosztowych i sprzedażowych (Integrator → Optima)

Po utworzeniu faktury w **Integratorze** (w module **EOD** lub **Faktury**) może ona zostać automatycznie wysłana do **Optimy**.

Faktury są przesyłane do **rejestru VAT**.

Aby integracja działała poprawnie, należy skonfigurować:

- **rejestr VAT zakupowy** – dla faktur kosztowych
- **rejestr VAT sprzedażowy** – dla faktur sprzedażowych

---

# Przesyłanie informacji o dekretacji faktur kosztowych

ThtgEsb może działać w dwóch trybach.

### Tryb 1

Elementy dekretacji z EOD są traktowane jako **osobne pozycje faktury**.  
Dokument zawiera informacje o **kwocie netto i brutto**, bez kategorii.

### Tryb 2

Elementy dekretacji są przesyłane jako **osobne pozycje faktury z przypisanymi kategoriami kosztów**.

System próbuje rozdzielić numery kont, np.: 501-432


zostaje rozdzielone na:

- **501 → Kategoria**
- **432 → Kategoria2**

⚠️ **Uwaga**

Plan kont w **Optimie** i **Integratorze** musi być **identyczny**.  
Jeżeli konto nie będzie zgodne, element faktury zostanie wysłany **bez przypisanych kategorii**.

---

# Tworzenie zapisów kasowych i bankowych

Integracja działa w dwóch kierunkach:

- **Integrator → Optima**
- **ThtgEsb → Optima**

ThtgEsb posiada integrację z aplikacjami bankowymi:

- **mBank**
- **PKO**

Dzięki temu dane mogą być wysyłane bezpośrednio do:

- Optimy
- Integratora

Aplikacje bankowe instalowane są **na serwerze klienta**.

Integrator umożliwia również **import wyciągów bankowych z wielu banków**.  
Po imporcie w Integratorze mogą one zostać automatycznie przesłane do Optimy.

---

# Procedura integracji

Proces integracji przebiega w następujących etapach:

1. **THTG** ustala z klientem zakres integracji.
2. Klient przekazuje dane dostępowe do **serwera oraz VPN** (jeżeli jest używany).
3. Klient tworzy **testową bazę danych** na podstawie istniejącej spółki w Optimie.
4. Klient tworzy użytkownika w Optimie dla **THTG** z dostępem do:
   - bazy testowej
   - baz produkcyjnych
5. THTG instaluje aplikację i testuje integrację na bazie testowej.
6. THTG przeprowadza **testy integracji z klientem**.
7. Po zakończeniu testów uruchamiana jest **integracja dla baz produkcyjnych**.

---

# Instalacja aplikacji

1. Rozpakuj dostarczone archiwum na serwerze z dostępem do Optimy.
2. Edytuj plik **config.json**.
3. Wprowadź dane użytkownika oraz konfigurację spółek.

### Parametry konfiguracji

- **optimaUser** – nazwa operatora w Optimie
- **optimaPassword** – hasło operatora
- **companies** – lista spółek

Dla każdej spółki podajemy:

- **name** – nazwa firmy w Optimie
- **taxId** – NIP spółki
- **accounts** – używane przy integracji wyciągów bankowych

---

# Przykładowa konfiguracja

```json
{
  "optimaUser": "Adam",
  "optimaPassword": "pwd",
  "companies": [
    {
      "name": "Zielona Sp. z o.o.",
      "taxId": "1234567890",
      "accounts": []
    },
    {
      "name": "Czerwona",
      "taxId": "2345678901",
      "accounts": []
    }
  ]
}
```
# Konfiguracja licencji

Domyślnie aplikacja wykorzystuje licencję:

**Moduł dostępowy (Kasa/Bank)**

Jeżeli używany jest moduł:

**Moduł dostępowy (Kasa/Bank Plus)**

należy zmienić wartość parametru **`applicationMode`** z:

 - [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0 ] 
 
 na 

- [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0].


---

# Testowanie konfiguracji

W celu weryfikacji poprawności konfiguracji, należy uruchomić aplikację **ThtgEsbService.exe** z argumentem test, np. .\ThtgEsbService.exe test. W przypadku błędu, aplikacja wyświetli komunikat w konsoli.


Jeżeli konfiguracja zawiera błędy, aplikacja wyświetli odpowiedni **komunikat w konsoli**.

---

# Włączenie automatycznej synchronizacji danych

W celu uruchomienia automatycznej synchronizacji, należy dodać uruchamianie aplikacji z argumentem invoices do harmonogramu zadań systemu. Zalecana częstotliwość uruchamiania to 5 minut. Poniżej przykład konfiguracji


[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/VT7cAYUTZUESKhYq-image-1772723021904.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/VT7cAYUTZUESKhYq-image-1772723021904.png)

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/yfoZux6ctiw9ZnJP-image-1772723029961.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/yfoZux6ctiw9ZnJP-image-1772723029961.png)
[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/p8SqmjnZuJlXmSr8-image-1772723040158.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/p8SqmjnZuJlXmSr8-image-1772723040158.png)

# Formularze kontaktowe

# Integracja formularzy WWW z THTG Integrator

**THTG Integrator** udostępnia **API**, dzięki któremu zgłoszenia wysyłane przez klientów na stronie internetowej mogą być automatycznie przekazywane do **rejestru kontaktów w THTG Integrator**.

Dokumentacja API jest przekazywana **na etapie wdrożenia systemu przez opiekuna wdrożenia**.

---

# Przekazywanie źródeł dotarcia klienta do THTG Integrator

API udostępnia pola umożliwiające przekazanie informacji o **źródle dotarcia klienta**.

Aby dane te były dostępne, konieczna jest odpowiednia obsługa zbierania informacji o źródle ruchu **po stronie strony internetowej (WWW)**.

---

# Zbieranie źródeł dotarcia klienta w WordPress

Do zbierania informacji o źródle dotarcia klienta można wykorzystać wtyczkę:

**[HandL UTM Grabber / Tracker](https://pomoc.thtg.io/attachments/27)**

W **wersji darmowej** plugin umożliwia:

- rejestrowanie parametrów **UTM**

Rejestrowanie źródeł z:

- **Facebook Ads**
- **Google Ads**

wymaga **wersji płatnej wtyczki**.

Po zainstalowaniu i skonfigurowaniu pluginu informacje o źródle klienta są dostępne:

- w **ciastkach (cookies)**
- w **[shortcode’ach WordPress (wp shortcode)](https://pomoc.thtg.io/attachments/28)**

Dane te można następnie przekazać do **API THTG Integrator** razem z formularzem kontaktowym.

# Integracja kalendarza z programem Outlook

Dzięki tej funkcjonalności możesz wyświetlać w **kalendarzu Outlook** wszystkie powiadomienia, które znajdują się w **kalendarzu THTG Integrator**.

⚠️ **Uwaga**  
Integracja działa **jednokierunkowo** – wydarzenia są przekazywane **z THTG do programu pocztowego**, a zmiany w Outlooku **nie są synchronizowane z THTG**.

---

# Integracja kalendarza z programem Outlook

## 1. Eksport kalendarza z THTG

1. Wejdź w **Menu boczne → Kalendarz**.
2. Kliknij **Eksportuj**.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/e4Sw9akH4sCwGajc-image-1772723233170.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/e4Sw9akH4sCwGajc-image-1772723233170.png)

---

## 2. Skopiowanie linku kalendarza

Po pojawieniu się okna **Eksport kalendarza**:

1. Skopiuj wygenerowany **link do kalendarza**.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/ANr8VkLTFOOcrq8s-image-1772723243653.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/ANr8VkLTFOOcrq8s-image-1772723243653.png)

---

## 3. Dodanie kalendarza w Outlook

1. Otwórz **Outlook** w przeglądarce.
2. Przejdź do **Kalendarza** (ikona kalendarza po lewej stronie).
3. W lewym panelu kliknij **Dodaj kalendarz**.
4. W oknie, które się pojawi, wybierz **Subskrybuj z sieci Web / Subscribe from web**.
5. **Wklej link skopiowany z platformy THTG** do kalendarza (np. kończący się na .ics).
6. Nadaj nazwę kalendarzowi.
7. Kliknij **Importuj**.
Kalendarz pojawi się w sekcji Inne kalendarze. 📅

Po wykonaniu tych kroków **kalendarz THTG zostanie połączony z kalendarzem Outlook**, a wszystkie powiadomienia z systemu będą widoczne w Outlooku.

[![zakladka kalendarz w outlook.jpg](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/cOvZynK0IGr0D9q7-zakladka-kalendarz-w-outlook.jpg)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/cOvZynK0IGr0D9q7-zakladka-kalendarz-w-outlook.jpg)

[![dodawanie kalendarza.jpg](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/OO5tlEFe4LwqrFxl-dodawanie-kalendarza.jpg)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/OO5tlEFe4LwqrFxl-dodawanie-kalendarza.jpg)

[![dodawanie kalendarzu z internetu.jpg](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/UaDgANZ1YBwxeXNA-dodawanie-kalendarzu-z-internetu.jpg)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/UaDgANZ1YBwxeXNA-dodawanie-kalendarzu-z-internetu.jpg)

---

## 6.Jak usunąć ten kalendarz

1. Wejdź ponownie do **Kalendarza**.  
2. W lewym panelu znajdź sekcję **Inne kalendarze**.  
3. Najedź myszką na nazwę dodanego kalendarza.  
4. Kliknij **trzy kropki (…)** obok nazwy.  
5. Wybierz **Usuń**.

Po usunięciu kalendarz zniknie i przestanie się aktualizować.

# Integracja z MBank - Konta powiernicze

Za pomocą tej funkcjonalności możesz zintegrować swoje konto bankowe z systemem THTG.

## Integracja z MBank – Konta powiernicze

### Integracja bezpośrednia

Po podpisaniu umowy z MBank na aplikację łączącą zainstaluj aplikację na swoim komputerze. Następnie przekaż do THTG klucz pozwalający na integrację systemu THTG z aplikacją łączącą.  
Pracownik THTG wykona dalsze kroki w celu integracji.

### Integracja pośrednia

Proszę przesłać do THTG plik **MT940**. Następnie pracownik THTG wykona dalsze kroki w celu integracji.  
Plik powinien zawierać szczegółową informację o kwocie zwolnienia dla każdego konta powierniczego klienta (umowy).

# Integracja z Ministerstwem Cyfryzacji - ustawa o jawności cen

## Podstawa prawna

Z dniem **11 lipca 2025 r.** wchodzi w życie obowiązek publikowania cen mieszkań przez deweloperów na ich stronach internetowych oraz przekazywania tych danych do Ministerstwa Cyfryzacji.  
Obowiązek ten wynika z nowelizacji ustawy z dnia **21 maja 2025 r. o jawności cen w sektorze mieszkaniowym** [(Dz. U. z 2025 r. poz. 758)](https://pomoc.thtg.io/attachments/29)

- Dla inwestycji, w których sprzedaż rozpocznie się **od 11 lipca 2025 r.**, obowiązek publikacji cen obowiązuje **od dnia rozpoczęcia sprzedaży**.
- Dla inwestycji, których sprzedaż rozpoczęła się **przed 11 lipca 2025 r.**, obowiązek wchodzi w życie **11 września 2025 r.**.
---

## Krok 1 – Założenie konta dostawcy danych

Pierwszym etapem jest rejestracja konta dostawcy danych na portalu: [dane.gov.pl](https://pomoc.thtg.io/attachments/30)

Instrukcja procesu dostępna pod adresem: [Instrukcja zakładania profilu dostawcy danych](https://pomoc.thtg.io/attachments/31)

Po rejestracji należy wysłać wiadomość e-mail w celu nadania uprawnień edytora.

### Wzór wiadomości

**Do:** kontakt@dane.gov.pl  
**Tytuł:** Założenie profilu dla dewelopera THTG-BUD Sp. z o. o.

**Treść:**

- Pełna nazwa dewelopera: THTG-BUD Sp. z o. o.
- Dane adresowe dewelopera: ul. Poznańska 12, 60-123 Poznań
- Adres strony internetowej dewelopera: deweloper.thtg.pl
- Adres poczty elektronicznej dewelopera (ogólny do firmy, np. biuro, sekretariat): biuro@deweloper.pl
- Numer telefonu (ogólny do firmy, np. biuro, sekretariat): +48 22 122 03 55
- Opcjonalnie numer faksu
- Numer REGON: 123456789
- Adres do doręczeń elektronicznych (e-Doręczeń), jeżeli występuje
- Imiona i nazwiska użytkowników, którym mają zostać nadane uprawnienia edytora:  
  Jan Nowak, Stefan Kowalski
- Adresy służbowej poczty elektronicznej (imienne w domenie służbowej, na które zostało zarejestrowane konto w portalu):


## Krok 2 – Konfiguracja integracji po stronie THTG Integrator

W trakcie oczekiwania na nadanie uprawnień należy w **THTG Integrator**:

- określić, które spółki i inwestycje mają być objęte raportowaniem do Ministerstwa Cyfryzacji,
- skonfigurować daty rozpoczęcia publikacji historii cen.

### Ustawienie daty rozpoczęcia publikacji cen dla inwestycji

W każdej inwestycji należy przejść do sekcji:

**Daty w inwestycji** → uzupełnić pole **Rozpoczęcie udostępniania historii**

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/6MyiTZUlmpNwP6ij-image-1773047621232.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/6MyiTZUlmpNwP6ij-image-1773047621232.png)

Data ta musi odpowiadać rzeczywistej dacie rozpoczęcia sprzedaży.  
Zmiany cen dokonane przed tą datą **nie będą publikowane**.

**Przypomnienie:**

- Dla inwestycji, których sprzedaż rozpoczęła się przed **11.07.2025 r.**, obowiązek raportowania rozpoczyna się **11.09.2025 r.**

---

## Krok 3 – Udostępnienie danych

Poniższy krok wykonaj dla **każdej spółki prowadzącej sprzedaż**.  
Jeżeli jedna osoba jest zgłoszonym edytorem w wielu spółkach, może wysłać wiadomość zbiorczą.

### Generowanie linków

W panelu **THTG Integrator**:

1. Przejdź do **Ustawienia → Organizacja → Spółki**.
2. Dla każdej spółki, w której prowadzona jest sprzedaż, wygeneruj link do udostępniania historii cen:
   - kliknij **„3 kropki” → Udostępnij historię cen inwestycji**
3. Skopiuj wygenerowany link.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/NHlCuQHyLq0S6jk4-image-1773047649194.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/NHlCuQHyLq0S6jk4-image-1773047649194.png)

### Zgłoszenie linków do portalu dane.gov.pl

Wygenerowane linki należy zgłosić do Ministerstwa Cyfryzacji, wysyłając e-mail na adres:

**kontakt@dane.gov.pl**

### Wzór wiadomości

**Do:** kontakt@dane.gov.pl  
**Tytuł:** Wniosek o uruchomienie automatycznego zasilania danych historii cen mieszkań

**Treść:**

- Imię i nazwisko osoby składającej wniosek: Jan Nowak
- Adres email edytora lub edytorów: jan.nowak@thtg.pl
- Nazwa dostawcy: zgodna z utworzoną w portalu dla dewelopera
- Adres URL określający lokalizację pliku XML:  
  https://lead.thtg.io/api/v1/public/prices/81f9450a-e71a-4811-aa38-ec44c871dafe.xml
- Częstotliwość aktualizacji danych: **codziennie**

---

# Najczęściej zadawane pytania

## Jakie dane są wysyłane?

Udostępniane są pliki z **historią cen na dany dzień**.

W plikach znajdują się dane o wszystkich typach systemowych z wyjątkiem:

- Zmiana lokatorska
- Lokal użytkowy

Dane są przekazywane dla produktów w statusach:

- **Dostępny**
- **Rezerwacja wstępna**
- **Potwierdzona rezerwacja**

Jeżeli produkt znajduje się w innym statusie:

- raportowana jest cena z **ostatniego dnia**, w którym produkt posiadał jeden z powyższych statusów,
- jeżeli taka cena nie istnieje, pobierana jest **pierwsza najstarsza cena**.

System może nie wysyłać produktów posiadających podpisaną umowę sprzedaży.  
W tym celu należy zaznaczyć opcję:

**„Nie wysyłaj produktów z podpisaną umową sprzedaży do Ministerstwa Cyfryzacji”.**

---

## Zakres udostępnianych danych

- cena brutto **m²** – jeżeli istnieje cena promocyjna, udostępniana jest promocyjna, w przeciwnym wypadku cena ofertowa
- **cena całkowita brutto** – jeżeli istnieje cena promocyjna, udostępniana jest promocyjna, w przeciwnym wypadku cena ofertowa
- **data zmiany ceny wraz z godziną**
- **numer projektowy produktu**
- **nazwa typu produktu**
- **nazwa inwestycji**

Jeżeli cena w danym dniu zmieni się kilkukrotnie, w pliku pojawi się **kilka rekordów dla danego produktu**.

---

## Z jakiego dnia dane są wysyłane?

Dane generowane są **codziennie** i pokazują stan na **dzień poprzedni**.

**Przykład:**

- **12.07** – w pliku znajdują się najświeższe ceny sprzed **12.07**

---

## Czy po uruchomieniu nowej inwestycji muszę ponownie wysyłać link do portalu dane.gov.pl?

**Nie.**

Jeżeli link dla danej spółki został już zgłoszony, wystarczy ustawić **datę rozpoczęcia udostępniania historii cen w nowej inwestycji**.  
Dane zostaną przekazane automatycznie po tej dacie.

# Kalendarz Google - integracja

## Integracja kalendarza Google

Aby dodać kalendarz THTG do swojego kalendarza Google, wykonaj poniższe kroki:

1. Wejdź w zakładkę **Kalendarz** w systemie **THTG**.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/UzIfukdyq1wVMRBw-image-1773047935478.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/UzIfukdyq1wVMRBw-image-1773047935478.png)

2. Wyeksportuj kalendarz przyciskiem **„Eksportuj”**.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/RNwS9BDmtSQqcg3V-image-1773047942184.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/RNwS9BDmtSQqcg3V-image-1773047942184.png)

3. Wejdź do **Kalendarza Google** i znajdź opcję dodania nowego kalendarza.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/EgZoy04zumxGIFjY-image-1773047949267.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/EgZoy04zumxGIFjY-image-1773047949267.png)

4. Wybierz pozycję **„Dodaj z adresu URL”**.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/Ni8YDdkhlvPE9ebs-image-1773047955790.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/Ni8YDdkhlvPE9ebs-image-1773047955790.png)

5. Wklej link skopiowany z systemu **THTG** i połącz go, klikając przycisk **„Dodaj kalendarz”**.

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/LyTQvaykOUnquuK5-image-1773047964490.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/LyTQvaykOUnquuK5-image-1773047964490.png)

# Symfonia THTG API

---

# Instalacja na IIS

## Wymagania

- Zainstalowany **IIS**
- **[ASP.NET Core Hosting Bundle](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-aspnetcore-8.0.28-windows-hosting-bundle-installer)**

---

# Instalacja aplikacji

1. Wypakuj odpowiednią wersję aplikacji.

2. Utwórz plik **appsettings.local.json** na podstawie **appsettings.json**.

3. Uzupełnij plik danymi, np.:

```json
{
  "Databases": [
    {
      "Name": "demo",
      "Server": "SERVERSQL",
      "Database": "BAZA_THTG",
      "User": "THTG",
      "Password": "THTG2"
    }
  ],
  "ApiKey": "2Tr5RsPkTGKAxC"
}
```
### Opis pól

- **Name** – przyjazna nazwa bazy (należy ją przekazać do THTG)
- **Server** – nazwa lub adres serwera bazy danych SQL
- **Database** – nazwa bazy danych spółki
- **User** – nazwa użytkownika Symfonii
- **Password** – hasło użytkownika Symfonii
- **ApiKey** – klucz autoryzacyjny (należy go przekazać do THTG)

5. Przejdź do **Menedżera IIS**.

6. Dodaj nową witrynę, przechodząc do:
[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/dzPWL2RiUpt8XGj0-image-1773048241372.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/dzPWL2RiUpt8XGj0-image-1773048241372.png)
7. Uzupełnij dane witryny
[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/xZJw5lSPw4ehB7GD-image-1773048261657.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/xZJw5lSPw4ehB7GD-image-1773048261657.png)

8. Wejdż w pulę aplikacji, zaznacz aplikację i wybierz Ustawienia zaawansowane
[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/QosvxmrD08cat4FX-image-1773048278210.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/QosvxmrD08cat4FX-image-1773048278210.png)
9. W sekcji Ogólne zmień Włącz aplikacje 32-bitowe z False na True
[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/6coy1IbevwQwuuzX-image-1773048298412.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/6coy1IbevwQwuuzX-image-1773048298412.png)
10. Zrestartuj pulę i aplikację

Po uruchomieniu należy przekazać THTG następujące informacje:

- Adres, na któym została uruchomiona aplikacja
- Przyjazne nazwy baz dla każdej zintegrowanej spółki
- Klucz autoryzacyjny

## Pliki do pobrania

- **ThtgSymfonia 1.6.0** (dla **Symfonia 26.0**) : [ThtgSymfonia160.zip](https://pomoc.thtg.io/attachments/48)
- **ThtgSymfoniaErp 1.6.0** (dla **Symfonia ERP 26.0**) : [ThtgSymfoniaErp160.zip](https://pomoc.thtg.io/attachments/49)

# Symfonia WebAPI

# Słownik

- **Integrator** – system Integrator THTG  
- **Symfonia** – system księgowy Symfonia  
- **WebAPI** – usługa stworzona przez Symfonię, pozwalająca na integrację systemów zewnętrznych z systemem księgowym Symfonia.  
  Link do opisu WebAPI: https://symfonia.pl/oprogramowanie/web-api

---

# Wstęp

**WebAPI** jest modułem dodatkowo płatnym.  

W przypadku posiadania wielu spółek wymagane jest uruchomienie wielu instancji **WebAPI**.

Instrukcja instalacji usługi:  
https://pomoc.symfonia.pl/Help/api/webapi/2022/123205

### Przykład konfiguracji

[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/EUdnRmw4eknNWjBV-image-1773048419847.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/EUdnRmw4eknNWjBV-image-1773048419847.png)
[![](https://pomoc.thtg.io/uploads/images/gallery/2026-03/scaled-1680-/7ADxfJokvTW5lUXj-image-1773048427142.png)](https://pomoc.thtg.io/uploads/images/gallery/2026-03/7ADxfJokvTW5lUXj-image-1773048427142.png)
---

# Wymagania

- uruchomiona usługa **WebAPI**
- link do publicznego adresu, za pomocą którego **Integrator** będzie komunikował się z **WebAPI**
- token autoryzacyjny
- nazwa spółki, której dotyczy konfiguracja

---

# Możliwości integracji

Integrator posiada następujące możliwości integracji z systemem **Symfonia**.

## Tworzenie kontrahentów [Integrator → Symfonia]

Po utworzeniu kontrahenta w **Integratorze** jest on automatycznie wysyłany do **Symfonii**.

Kontrahenci wysyłani są:

- po ich utworzeniu lub modyfikacji w sekcji **Klient → Kontrahent**
- po utworzeniu i podpisaniu **umowy dla klienta lub klientów**

W przypadku umowy dla wielu klientów tworzony jest **jeden kontrahent w Symfonii**, który zawiera dane wszystkich klientów.

## Tworzenie faktur kosztowych i sprzedażowych [Integrator → Symfonia]

Po utworzeniu faktury w **Integratorze** w module **EOD** lub w module **Faktur**, może ona zostać automatycznie wysłana do **Symfonii** do odpowiedniej sekcji systemu.

Faktury są **zadekretowane zgodnie z konfiguracją w Integratorze**.

Do **Symfonii nie są wysyłane pliki PDF faktur**.

---

# Procedura integracji

1. **THTG** ustala z klientem zakres integracji.
2. Klient instaluje **WebAPI** i przekazuje THTG dane do **bazy testowej utworzonej na podstawie bazy istniejącej**.
3. **THTG** wewnętrznie testuje integrację.
4. **THTG** testuje integrację wspólnie z klientem.
5. Klient konfiguruje **WebAPI dla pozostałych baz** i przekazuje dane do THTG.
6. **THTG** uzupełnia konfigurację w Integratorze i uruchamia integrację.

# Instrukcja konfiguracji importu faktur XML z programu THTG do Comarch ERP Optima (w Chmurze)

## 1. Cel konfiguracji

Celem konfiguracji jest umożliwienie przesyłania faktur z programu **THTG** do **Comarch ERP Optima** przy pomocy plików **XML** z wykorzystaniem mechanizmu **Pracy Rozproszonej**.

Schemat działania integracji:

1. Program **THTG generuje plik XML z fakturą**.  
2. Plik zapisywany jest w **ustalonym katalogu wymiany**.  
3. **Comarch ERP Optima importuje plik XML**.  
4. W systemie tworzony jest **dokument handlowy (np. faktura sprzedaży)**.

---

# 2. Włączenie pracy rozproszonej w Optimie

1. Uruchomić **Comarch ERP Optima**.  
2. Przejść do menu: System → Konfiguracja → Firma → Ogólne → Praca rozproszona  
3. Włączyć obsługę pracy rozproszonej oraz ustawić tryb wymiany danych XML.  
4. Zapisać zmiany.

---

# 3. Ustawienie katalogu wymiany plików XML

Aby Optima mogła odczytać dokumenty przesyłane z THTG, należy wskazać katalog, w którym będą zapisywane pliki XML.

1. Przejść do: System → Konfiguracja → Stanowisko → Handel → Parametry
2. W polu **Katalog importu dokumentów XML** wskazać folder, np.: C:\Optima_XML\

3. Zatwierdzić ustawienia.

Od tego momentu pliki XML zapisane w tym katalogu mogą być importowane do systemu.

---

# 4. Generowanie pliku XML w programie THTG

Program **THTG** powinien generować pliki XML zgodne z formatem obsługiwanym przez **Comarch ERP Optima**.

Każda wystawiona faktura powinna zostać zapisana jako plik XML, np.: faktura_123.xml

Plik powinien zostać zapisany w katalogu wskazanym w konfiguracji Optimy, np.: C:\Optima_XML\


---

# 5. Import faktur XML w Comarch ERP Optima

Po zapisaniu pliku XML w katalogu wymiany należy wykonać import dokumentów.

1. Uruchomić **Comarch ERP Optima**.  
2. Przejść do: Narzędzia → Praca rozproszona
3. Wybrać opcję **Import**.  
4. Wskazać plik XML z katalogu wymiany.  
5. Zatwierdzić import.

Po poprawnym imporcie dokument zostanie dodany do systemu.

---

# 6. Weryfikacja poprawności importu

Po zakończeniu importu należy sprawdzić, czy dokument został poprawnie utworzony.

Dokument można znaleźć w: Handel → Faktury sprzedaży
lub
Rejestry VAT → Rejestr sprzedaży


---

# 7. Wymagania dotyczące danych w pliku XML

Aby import przebiegł poprawnie, plik XML musi zawierać m.in.:

- dane kontrahenta,
- numer dokumentu,
- datę wystawienia,
- pozycje towarowe lub usługowe,
- ceny netto/brutto,
- stawki VAT.

Jeżeli w bazie danych nie istnieje wskazany kontrahent lub towar, Optima może utworzyć je automatycznie (jeśli konfiguracja na to pozwala).

---

# 8. Najczęstsze problemy

## Brak możliwości importu pliku XML

Przyczyną może być:

- niepoprawna struktura pliku XML,
- brak wymaganych danych,
- niezgodny format dokumentu.

---

## Dokument nie pojawia się w systemie

Należy sprawdzić:

- czy plik XML znajduje się w poprawnym katalogu,
- czy wykonano import w module **Praca rozproszona**,
- czy użytkownik pracuje na właściwej bazie danych.

---

# 9. Podsumowanie

Integracja programu **THTG** z **Comarch ERP Optima** polega na wymianie danych poprzez pliki **XML** w mechanizmie **Pracy Rozproszonej**.

Proces obejmuje:

1. konfigurację pracy rozproszonej w Optimie,  
2. wskazanie katalogu wymiany plików XML,  
3. generowanie plików XML w programie THTG,  
4. import dokumentów XML do systemu Optima.

Po poprawnej konfiguracji możliwe jest regularne przenoszenie faktur z programu THTG do systemu księgowego.


[Instrukcja Video](https://pomoc.thtg.io/attachments/37)

# Integracje systemów księgowych z THTG Integrator

## Comarch ERP Optima

### Architektura integracji

Integracja realizowana jest przez aplikację pośredniczącą **ThtgEsb**, instalowaną na serwerze klienta z dostępem do Optimy. Komunikacja odbywa się przez szynę danych THTG, dzięki czemu serwer z Optimą nie musi być wystawiony do Internetu. ThtgEsb musi jedynie posiadać dostęp do Internetu.

```text
THTG Integrator
       ⇅
    Szyna danych
       ⇅
     ThtgEsb
       ⇅
Comarch ERP Optima
```

### Wymagania

* dostęp do serwera z Optimą,
* instalacja aplikacji ThtgEsb,
* login i hasło operatora Optimy,
* lista baz danych/spółek,
* testowa baza danych utworzona na podstawie produkcyjnej,
* wolna licencja użytkownika Optimy dla ThtgEsb.

> Integracja nie współpracuje z wersją chmurową Comarch ERP Optima.

### Dane wymagane od klienta

* dostęp do serwera,
* dane VPN (jeżeli wykorzystywany),
* operator Optimy dla THTG,
* dostęp do bazy testowej i produkcyjnej,
* konfiguracja spółek:

  * nazwa firmy,
  * NIP,
  * rachunki bankowe (jeżeli wykorzystywane).

### Zakres integracji

#### Kontrahenci (THTG → Optima)

Automatyczne tworzenie kontrahentów:

* po utworzeniu kontrahenta,
* po modyfikacji kontrahenta,
* po podpisaniu umowy.

Weryfikacja duplikatów odbywa się na podstawie:

* NIP,
* PESEL.

Automatyczne generowanie kodów:

* `K_{id klienta}`
* `KT_{id kontrahenta}`

Przykłady:

* `K_3123`
* `KT_3121`

#### Faktury (THTG → Optima)

Obsługiwane są:

* faktury kosztowe,
* faktury sprzedażowe.

Dokumenty przesyłane są bezpośrednio do rejestrów VAT:

* zakupowego,
* sprzedażowego.

#### Dekretacja kosztów

**Tryb 1**

* elementy dekretacji przesyłane jako osobne pozycje faktury,
* brak przypisanych kategorii kosztowych.

**Tryb 2**

* elementy dekretacji przesyłane jako osobne pozycje faktury,
* automatyczne przypisywanie kategorii kosztowych na podstawie planu kont.

Przykład:

```text
501-432

501 → Kategoria
432 → Kategoria2
```

> Plan kont w Optimie i Integratorze musi być identyczny. W przeciwnym przypadku pozycje zostaną przesłane bez przypisanych kategorii.

#### Operacje bankowe

Obsługiwane są:

* zapisy kasowe,
* zapisy bankowe,
* import wyciągów bankowych.

Dostępne integracje bankowe:

* mBank,
* PKO BP.

### Procedura wdrożenia

1. Ustalenie zakresu integracji.
2. Przekazanie dostępu do serwera oraz VPN.
3. Utworzenie bazy testowej.
4. Utworzenie operatora Optimy dla THTG.
5. Instalacja ThtgEsb.
6. Testy integracji na bazie testowej.
7. Testy wspólne z klientem.
8. Uruchomienie integracji na środowisku produkcyjnym.

---

## Symfonia WebAPI

### Architektura integracji

Integracja wykorzystuje oficjalny moduł **Symfonia WebAPI**.

```text
THTG Integrator
       ⇅
   Symfonia WebAPI
       ⇅
      Symfonia
```

### Wymagania

* uruchomiona usługa WebAPI,
* publiczny adres usługi WebAPI,
* token autoryzacyjny,
* nazwa spółki.

> Moduł Symfonia WebAPI jest dodatkowo płatny.

> W przypadku wielu spółek wymagane jest uruchomienie osobnych instancji WebAPI.

### Dane przekazywane do THTG

* adres WebAPI,
* token autoryzacyjny,
* nazwa spółki.

### Zakres integracji

#### Kontrahenci (THTG → Symfonia)

Automatyczne tworzenie kontrahentów:

* po utworzeniu kontrahenta,
* po modyfikacji kontrahenta,
* po podpisaniu umowy.

Dla umów obejmujących wielu klientów tworzony jest jeden kontrahent zawierający dane wszystkich klientów.

#### Faktury (THTG → Symfonia)

Obsługiwane są:

* faktury kosztowe,
* faktury sprzedażowe.

Źródła dokumentów:

* moduł EOD,
* moduł Faktury.

Faktury są dekretowane zgodnie z konfiguracją Integratora.

> Do Symfonii nie są przesyłane pliki PDF faktur.

### Procedura wdrożenia

1. Ustalenie zakresu integracji.
2. Instalacja i konfiguracja WebAPI.
3. Utworzenie bazy testowej.
4. Testy integracji po stronie THTG.
5. Testy wspólne z klientem.
6. Konfiguracja pozostałych baz.
7. Uruchomienie integracji produkcyjnej.

---

## Symfonia THTG API

### Architektura integracji

Rozwiązanie wykorzystuje dedykowane API przygotowane przez THTG i instalowane na serwerze klienta.

```text
THTG Integrator
       ⇅ HTTPS
  Symfonia THTG API
       ⇅
      SQL Server
       ⇅
      Symfonia
```

### Wymagania

* IIS,
* ASP.NET Core Hosting Bundle,
* dostęp do bazy danych Symfonii.

### Konfiguracja

Konfiguracja realizowana jest poprzez plik `appsettings.local.json`.

Przykład:

```json
{
  "Databases": [
    {
      "Name": "demo",
      "Server": "SERVERSQL",
      "Database": "BAZA_THTG",
      "User": "THTG",
      "Password": "THTG2"
    }
  ],
  "ApiKey": "2Tr5RsPkTGKAxC"
}
```

### Opis parametrów

| Parametr | Opis                                      |
| -------- | ----------------------------------------- |
| Name     | Przyjazna nazwa bazy przekazywana do THTG |
| Server   | Nazwa lub adres serwera SQL               |
| Database | Nazwa bazy danych spółki                  |
| User     | Użytkownik Symfonii                       |
| Password | Hasło użytkownika Symfonii                |
| ApiKey   | Klucz autoryzacyjny przekazywany do THTG  |

### Dane przekazywane do THTG

Po uruchomieniu aplikacji klient przekazuje:

* adres aplikacji,
* przyjazne nazwy baz dla każdej spółki,
* klucz autoryzacyjny API.

### Charakterystyka rozwiązania

W porównaniu do Symfonia WebAPI:

* nie wymaga zakupu modułu Symfonia WebAPI,
* wykorzystuje dedykowane API THTG,
* umożliwia obsługę wielu spółek w ramach jednej instalacji,
* komunikacja realizowana jest przez HTTPS.

---

# Porównanie rozwiązań

| Obszar                   | Comarch ERP Optima                 | Symfonia WebAPI                           | Symfonia THTG API             |
| ------------------------ | ---------------------------------- | ----------------------------------------- | ----------------------------- |
| Komponent integracyjny   | ThtgEsb                            | Symfonia WebAPI                           | Symfonia THTG API             |
| Dostęp do Internetu      | ThtgEsb                            | WebAPI                                    | IIS / API                     |
| Dodatkowa licencja       | Zalecana osobna licencja operatora | Płatny moduł WebAPI                       | Brak modułu WebAPI            |
| Kontrahenci              | Tak                                | Tak                                       | Tak                           |
| Faktury sprzedażowe      | Tak                                | Tak                                       | Tak                           |
| Faktury kosztowe         | Tak                                | Tak                                       | Tak                           |
| Dekretacja               | Tak                                | Tak                                       | Tak                           |
| Operacje bankowe         | Tak                                | Brak w dokumentacji                       | Brak w dokumentacji           |
| Obsługa wielu spółek     | Tak                                | Osobna instancja WebAPI dla każdej spółki | Tak                           |
| Wersja chmurowa          | Nieobsługiwana                     | Zależna od środowiska Symfonii            | Zależna od środowiska klienta |
| Publiczny adres wymagany | Nie                                | Tak                                       | Tak                           |