EN

Webová příručka PaymentService

Hlavní stránka / Dokumentace / 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 na základě variabilního symbolu a částky; u přijatých faktur a ostatních závazků se navíc porovnávají čísla účtů, ze kterého a na který platba odešla, uvádí-li je e-mail banky. Platba se spáruje jen tehdy, odpovídá-li jí právě jeden doklad, a s fakturou jen tehdy, nese-li variabilní symbol.
  • Spárované doklady jsou automaticky označeny jako částečně nebo plně uhrazené. Částečně se faktura uhradí jen tehdy, je-li v ERP povoleno párování částečných úhrad (výchozí stav); jinak musí částka platby odpovídat částce zbývající k úhradě. Ostatní pohledávky a závazky se spárují jen platbou v plné výši dokladu včetně DPH.
  • 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“. Je-li úhrada spárována s dokladem, je automaticky aktualizován i tento doklad; po spárování s vydanou fakturou nebo vydanou zálohovou fakturou je informace o úhradě zaslána také e-mailem (viz kapitola 10).

2. Podporované banky

  • Raiffeisenbank
  • 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

Služba PaymentService rozpozná e-mail banky podle adresy jeho odesílatele, takže e-mail musí do technologické schránky přijít přímo z adresy banky; přeposlaný e-mail se nezpracuje. Podporované měny jsou CZK, EUR a USD, u banky FIO jen CZK.

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í.

Služba PaymentService rozpoznává e-maily banky podle adresy odesílatele uvedené ve zprávě. Technologickou schránku je proto vhodné zabezpečit tak, aby přijímala jen poštu, kterou poštovní server ověří jako odeslanou bankou (například kontrolou SPF, DKIM a DMARC nebo pravidlem, které jinou poštu odmítne), a její adresu nezveřejňovat.

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 – Mail.ReadWrite“, typ „Aplikace“
      • Název rozhraní API „Microsoft Graph – User.Read.All“, typ „Aplikace“
    • Stahuje-li služba e-maily přes POP3 s přihlašováním OAuth2 (klíč „pop3OAuth“), je navíc potřeba oprávnění „Office 365 Exchange Online – POP.AccessAsApp“, typ „Aplikace“; aplikace musí být zároveň zaregistrovaná v Exchange Online a mít přístup k technologické schránce.
    • Oprávnění „Microsoft Graph – Calendars.ReadWrite“ a „Microsoft Graph – Group.ReadWrite.All“ služba nepotřebuje; jsou potřeba jen tehdy, sdílí-li registraci aplikace (soubor „MicrosoftOAuth.json“) i služba CRMService nebo propojení ERP s OneDrive a Microsoft Teams.

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-MM-dd}.log“
  • Detailní výpis komunikace se službami Microsoft je uveden v samostatném souboru „Logs\Office365-{yyyy-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é služba PaymentService nepracuje (nestahuje ani nezpracovává e-mailové zprávy)
  • stopTo – koncový čas technologické pauzy ve formátu „HH:mm“, během které služba PaymentService nepracuje
  • 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, případně s číslem portu ve tvaru „název serveru:číslo portu“ (výchozí port je 110); zabezpečené spojení SSL se použije jen na portu 995 (například „pop3.firma.cz:995“), na jiném portu se služba připojí bez SSL
  • 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í zástupce „PaymentService - user.lnk“. Zástupce „PaymentService - user.lnk“ vznikne automaticky spuštěním programu „PaymentService.exe“.
  • Zástupce „PaymentService - user.lnk“ otevře dialog instalace služby. V něm je potřeba nastavit Startup mode na „Automatic“ a Account na „LocalSystem“; instalace služby se dokončí tlačítkem „Install“.
  • Název, pod kterým se služba nainstaluje a zobrazí v seznamu služeb operačního systému Windows, lze změnit volitelným parametrem „ServiceName“ v hlavním konfiguračním souboru služby „PaymentService.exe.config“. Není-li parametr uveden, použije se výchozí název „PaymentService“. Nastavení jedinečného názvu je užitečné zejména tehdy, když je na jednom serveru provozováno více nezávislých instalací služby a je potřeba je v seznamu služeb od sebe odlišit.

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

Podadresáře se zálohami starší než 6 měsíců služba sama maže, stejně jako logové soubory starší než jeden rok.

V jednom běhu služba PaymentService zpracuje nejvýše 500 e-mailových zpráv z technologické schránky; zbytek zpracuje v dalším běhu. Každá e-mailová zpráva se zapisuje v samostatné transakci a informační e-mail o platbě (viz kapitola 10) odejde až po jejím zápisu. Zpracování, které skončí chybou, tak v databázi nic nezanechá; služba běh ukončí a zprávu i všechny další zpracuje v dalších bězích. Zprávu, kterou se nepodařilo ani stáhnout z technologické schránky, služba přeskočí a pokračuje další; stáhnout ji zkusí znovu v dalším běhu. Selže-li zpracování potřetí, uloží se kopie zprávy do podadresáře „Failed“ ve stejném adresáři jako „PaymentService.exe“, zpráva se smaže z technologické schránky (soubor z adresáře „emlDir“ se smaže) a do logového souboru se zapíše chyba.

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

Po spárování platby s vydanou fakturou nebo vydanou zálohovou fakturou je zasílán informační e-mail s předmětem „Info o platbě“ z adresy uvedené v klíči „infoFrom“ na adresu uvedenou v klíči „infoTo“, v kopii na adresu v klíči „infoCc“. Není-li klíč „infoFrom“ nebo „infoTo“ vyplněn, informační e-mail se nezasílá. Při částečné úhradě obsahuje text e-mailu i částku, která zbývá k úhradě. Je-li v klíči „infoTo“ adresa e-mailové brány pro SMS (končící na „@sms.eurotel.cz“, „@sms.cz.o2.com“ nebo „@vodafonemail.cz“), odešle se zkrácená zpráva. 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.