EN

Webová příručka PaymentService

Hlavní stránka / Podpora / Příručky /

Webová příručka PaymentService

EN

1. Základní informace

PaymentService je služba, která běží na pozadí operačního systému Windows, a automaticky vytváří bankovní úhrady, označuje faktury a ostatní závazky jako uhrazené na základě komunikace s bankou. Instaluje se jako doplněk k aplikaci NET Genium ERP a vyžaduje technologickou schránku, do které jsou bankou zasílány e-mailové zprávy o příchozích a odchozích platbách. Z e-mailových zpráv doručených do technologické schránky automaticky vytváří bankovní úhrady a přiřazuje je ke konkrétním fakturám nebo ostatním závazkům.

  • Základní podmínkou je, že banka musí podporovat zasílání e-mailových zpráv o příchozích a odchozích platbách.
  • Platby jsou automaticky spárovány s příslušnými doklady v NET Geniu buď na základě variabilního symbolu a částky, nebo na základě čísla účtu a částky.
  • Spárované doklady jsou automaticky označeny jako částečně nebo plně uhrazené.
  • Služba funguje jak pro příchozí, tak i odchozí platby.

Při zaznamenání platby je automaticky vytvořen záznam o této úhradě v aplikaci „Banka“ v tabulce „Bankovní úhrady“. Automaticky je také aktualizován i příslušný doklad, kterého se úhrada týká a informace o této úhradě je také zaslána na definovaný e-mail v nastavení služby.

2. Podporované banky

  • eBanka
  • Raiffaisenbank
  • Komerční banka
  • FIO
  • Česká spořitelna – pouze odchozí platby (hrazení přijatých faktur a ostatních závazků) a navíc se musí při každé odchozí platbě nastavit odeslání emailu
  • UniCredit bank

3. Vyžadované soubory

Pro fungování PaymentService je nutné mít v jeho adresáři soubory:

  • PaymentService.exe
  • ERP.dll
  • ngef.dll
  • NETGeniumConnection.dll

+ konfigurační XML soubor pro každou technologickou schránku.

4. Technologická schránka

Nutnou podmínkou pro službu PaymentService je existence technologické schránky, do které jsou bankou zasílány e-mailové zprávy o příchozích a odchozích platbách. Obvyklým názvem je například „ps@firma.cz“ resp. „ps“ před zavináčem a s doménou dané společnosti.

Samotné zasílání e-mailových zpráv o příchozích a odchozích platbách je nutné provést ručně v aplikaci dodávané poskytovatelem bankovních služeb, typicky v internetovém bankovnictví.

5. Konfigurace Azure Active Directory

PaymentService vyžaduje dodatečnou ruční konfiguraci Azure Active Directory, resp. Microsoft Entra ID v případě, že stahuje e-maily z technologické schránky provozované pomocí cloudových služeb Microsoftu.

5.1. Konfigurace na portálu „https://portal.azure.com“

  • Registrace aplikace „NET Genium“ na webové stránce https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
    • česky: portal.azure.com / Registrace aplikací
    • anglicky: portal.azure.com / App registrations
    • NET Genium jako název aplikace
    • Zjištění ID aplikace (klienta), který je automaticky vytvořen při registraci aplikace
      • česky: ID aplikace (klienta)
      • anglicky: Application (client) ID
    • Zjištění ID adresáře (tenanta), který je automaticky vytvořen při registraci aplikace
      • česky: ID adresáře (tenanta)
      • anglicky: Directory (tenant) ID
    • Vytvoření tajného kódu klienta
      • česky: portal.azure.com / Registrace aplikací / NET Genium / Certifikáty a tajné kódy / Nový tajný kód klienta
      • anglicky: portal.azure.com / App registrations / NET Genium / Certificates & secrets / New client secret
    • Nastavení oprávnění API pro Microsoft Graph
      • česky: portal.azure.com / Registrace aplikací / NET Genium / Oprávnění rozhraní API / Přidat oprávnění / Microsoft Graph
      • anglicky: portal.azure.com / App registrations / NET Genium / API permissions / Add a permission / Microsoft Graph
      • Název rozhraní API „Microsoft Graph – Calendars.ReadWrite“, typ „Aplikace“
      • Název rozhraní API „Microsoft Graph – Group.ReadWrite.All“, typ „Aplikace“
      • Název rozhraní API „Microsoft Graph – Mail.ReadWrite“, typ „Aplikace“
      • Název rozhraní API „Microsoft Graph – User.Read.All“, typ „Aplikace“

5.2. Konfigurace NET Genia

  • Vytvoření konfiguračního souboru „NETGenium\Config\MicrosoftOAuth.json“
    • Obsah souboru nastavit na: „{"web":{"client_id":"ID aplikace (klienta)","tenant_id":"ID adresáře (tenanta)","auth_uri":"https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize","token_uri":"https://login.microsoftonline.com/organizations/oauth2/v2.0/token","client_secret":"tajný kód klienta"}}“

5.3. Postup při ladění chyb nebo v případě nefunkčního stahování e-mailů

5.3.1. Obecné

  • PaymentService ukládá průběh stahování e-mailů včetně případných chyb do logového souboru „Logs\{yyyy-dd-MM}.log“
  • Detailní výpis komunikace se službami Microsoft je uveden v samostatném souboru „Logs\Office365-{yyyy-dd-MM}.log“
  • Detailní výpis komunikace s POP3 serverem je uveden v samostatném souboru „Logs\POP3-{yyyy-dd-MM}.log“

5.3.2. Invalid client secret provided…

  • Server vrací chybu: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID
  • Zkontrolovat, že je v „MicrosoftOAuth.json“ správná hodnota „client_secret“

5.3.3. Application with identifier 'xxxxxxxxxx' was not found…

  • Server vrací chybu: Application with identifier 'xxxxxxxxxx' was not found in the directory 'firma s.r.o'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant.
  • Zkontrolovat, že je v „MicrosoftOAuth.json“ správná hodnota „tenant_id“

5.3.4. Access is denied. Check credentials and try again.

  • Pokud server vrací chybu: {"error":{"code":"ErrorAccessDenied","message":"Access is denied. Check credentials and try again."}}
  • Zkontrolovat, že má účet nastavená oprávnění API pro Microsoft Graph

6. Import e-mailových zpráv

PaymentService umí importovat existující „eml“ soubory, což jsou e-mailové zprávy uložené ve svém originálním formátu. Pro tyto účely je potřeba vytvořit importní adresář a nastavit jeho absolutní cestu na disku do konfiguračního souboru pod atribut „emlDir“. PaymentService čte soubory v tomto adresáři, zpracovává je standardním způsobem jako ostatní stažené e-mailové zprávy z poštovního serveru, a následně zpracované soubory z importního adresáře smaže.

7. Konfigurační soubor

Ke každé technologické schránce je potřeba vytvořit konfigurační XML soubor, a umístit jej do stejného adresáře jako „PaymentService.exe“. Příklad konfiguračního souboru:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>

   <add key="rootPath" value="C:\inetpub\wwwroot\netgenium" />

   <add key="stopFrom" value="00:00" />
   <add key="stopTo" value="06:00" />

   <add key="smtpServer" value="localhost" />

   <add key="errorFrom" value="paymentservice@firma.cz" />
   <add key="errorTo" value="support@netgenium.com" />

   <add key="pop3Email" value="ps@firma.cz" />
   <add key="pop3OAuth" value="true" />

   <add key="pop3Url" value="pop3.firma.cz" /> 
   <add key="pop3Name" value="ps@firma.cz" />
   <add key="pop3Password" value="pop3heslo" />

   <add key="emlDir" value="D:\Services\PaymentService\eml" />

   <add key="infoFrom" value="banka@firma.cz" />
   <add key="infoTo" value="finance@firma.cz" />
   <add key="infoCc" value="" />

  </appSettings>
</configuration>
  • rootPath – absolutní cesta na disku k adresáři NET Genia
  • stopFrom – počáteční čas technologické pauzy ve formátu „HH:mm“, během které se služba PaymentService nebude připojovat do technologické schránky
  • stopTo – koncový čas technologické pauzy ve formátu „HH:mm“, během které se služba PaymentService nebude připojovat do technologické schránky
  • smtpServer – adresa poštovního serveru odchozí pošty
  • errorFrom – e-mailová adresa, ze které jsou zasílány notifikace o případných chybách ve službě PaymentService
  • errorTo – e-mailová adresa, na kterou jsou zasílány notifikace o případných chybách ve službě PaymentService
  • pop3Email – e-mailová adresa technologické schránky
  • pop3OAuth – příznak, zda se má pro přihlašování používat zvýšené zabezpečení OAuth2 spolu s konfiguračním souborem „MicrosoftOAuth.json“
  • pop3Url – adresa poštovního serveru příchozí pošty (pro SSL zabezpečení je možné použít syntaxi „název serveru:číslo portu“)
  • pop3Name – přihlašovací jméno k technologické schránce
  • pop3Password – heslo k technologické schránce
  • emlDir – absolutní cesta na disku k adresáři, ze kterého služba PaymentService vyčítá a zpracovává „eml“ soubory
  • infoFrom – e-mailová adresa, ze které bude zaslána notifikace o provedené platbě
  • infoTo – e-mailová adresa, na kterou bude zaslána notifikace o provedené platbě
  • infoCc – volitelná e-mailová adresa (kopie), na kterou bude zaslána notifikace o provedené platbě

Všechny e-mailové zprávy, které dorazí do technologické schránky, jsou po jejich zpracování smazány.

8. Instalace služby

  • PaymentService je služba, která běží na pozadí operačního systému Windows, a automaticky se aktivuje a stahuje e-maily každých 10 minut. Nestačí tedy prosté spuštění programu „PaymentService.exe“, ale je nutná instalace služby pomocí souboru „PaymentService.exe - user.lnk“. Soubor „PaymentService.exe - user.lnk“ vznikne automaticky spuštěním programu „PaymentService.exe“.
  • Po spuštění programu „PaymentService.exe“ zkontrolujte nastavení dialogu. Startup mode nastavte na „Automatic“ a Account zvolte „LocalSystem“. Instalaci služby dokončíte kliknutím na tlačítko „Install“.

Obrázek.png

  • Odinstalaci programu provedete také spuštěním programu „PaymentService.exe“ a kliknutím na tlačítko „Uninstall“.

9. Zálohování stažených e-mailových zpráv

Kopie všech e-mailových zpráv doručených do technologické schránky se automaticky ukládají do podadresáře „POP3Downloads\yyyy-MM-dd“, který je umístěn ve stejném adresáři jako „PaymentService.exe“. E-mailové zprávy jsou ukládány pod náhodným názvem (GUID.eml), a jsou zařazeny do podadresáře, jehož název identifikuje den, ve kterém byla e-mailová zpráva stažena.

  • Příklad:
D:\Services\PaymentService\POP3Downloads\2013-05-28\154c463d-386a-4b61-bf0d-6b2cd91a1bcb.eml

10. Odesílání notifikačních zpráv

Při každé identifikaci a spárování platby s příslušným dokladem je zasílán informační e-mail na adresu uvedenou v konfiguračním souboru. Příklad textu e-mailu notifikace:

Vydaná faktura č. 130100024 vystavená společnosti Smetáček a lopatka, spol. s r.o. ve výši 10 890,00 CZK byla uhrazena.

11. Upozornění

Služba PaymentService je závislá na e-mailových zprávách a jejich obsahu, které zasílá příslušná banka. Pokud tedy banka např. nezasílá e-mail při úhradě menší než 100 Kč, PaymentService tento pohyb nezachytí. Stejně tak služba není schopná zachytit např. platby zprostředkované inkasem nebo trvalým příkazem. Proto se nedoporučuje PaymentService používat jako jediný a plnohodnotný nástroj k přiřazování plateb jednotlivým dokladům. Hojně je využívána např. možnost importování měsíčního výpisu z účtu do NET Genia a následnému automatickému spárování plateb na základě něj. Tuto funkcionalitu lze využívat souběžně bez omezení se službou PaymentService.