EN

Webová příručka PaymentService

Hlavní stránka / Produkty / Knihovna aplikací / Enterprise Resource Planning / Modul Finance / PaymentService /

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 (https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth).

Konfigurace Azure Active Directory, resp. Microsoft Entra ID se skládá z následujících kroků:

  • Konfigurace NET Genia 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
      • portal.azure.com / Registrace aplikací
      • 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
        • ID aplikace (klienta)
        • Application (client) ID
      • Zjištění ID adresáře (tenanta), který je automaticky vytvořen při registraci aplikace
        • ID adresáře (tenanta)
        • Directory (tenant) ID
      • Vytvoření tajného kódu klienta
        • portal.azure.com / Registrace aplikací / NET Genium / Certifikáty a tajné kódy / Nový tajný kód klienta
        • portal.azure.com / App registrations / NET Genium / Certificates & secrets / New client secret
      • Nastavení oprávnění API pro Office 365 Exchange Online
        • portal.azure.com / Registrace aplikací / NET Genium / Oprávnění rozhraní API / Přidat oprávnění / Rozhraní API, která používá moje organizace / Office 365 Exchange Online
        • portal.azure.com / App registrations / NET Genium / API permissions / Add a permission / APIs my organization uses / Office 365 Exchange Online
        • Název rozhraní API „POP.AccessAsApp“, typ „Aplikace“
        • Název rozhraní API „IMAP.AccessAsApp“, typ „Aplikace“

Obrázek.png

  • Vytvoření konfiguračního souboru „MicrosoftOAuth.json“ v adresáři „Config“ daného NET Genia, ve kterém mají být vytvářeny bankovní úhrady
    • 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"}}”
  • Propojení NET Genia s technologickou schránkou (https://www.youtube.com/watch?v=bMYA-146dmM) v aplikaci PowerShell pomocí následujícího skriptu:
    • Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted
    • Install-Module -Name ExchangeOnlineManagement
    • Install-Module Microsoft.Graph
    • Install-Module -Name AzureAD
    • Import-Module AzureAD
    • Import-Module ExchangeOnlineManagement
    • Connect-AzureAD -Tenant ID adresáře (tenanta)
    • Connect-ExchangeOnline -Organization ID adresáře (tenanta)
    • $myapp = Get-AzureADServicePrincipal -SearchString "NET Genium"
    • New-ServicePrincipal -AppId $myapp.AppId -ServiceId $myapp.ObjectId -DisplayName "Service Principal for POP3/IMAP Services"
    • Add-MailboxPermission -Identity "ps@firma.cz" -User $myapp.ObjectId -AccessRights FullAccess

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="pop3Url" value="pop3.firma.cz" />
   <add key="pop3Name" value="ps@firma.cz" />
   <add key="pop3Password" value="pop3topsecret" />
   <add key="pop3OAuth" value="true" />

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

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

  </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
  • 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
  • pop3OAuth – příznak, zda se má pro přihlašování používat zvýšené zabezpečení OAuth2
  • 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ě
  • emlDir – absolutní cesta na disku k adresáři, ze kterého služba PaymentService vyčítá a zpracovává „eml“ soubory

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.