Webová příručka InvoiceService

1. Základní informace

InvoiceService je služba, která běží na pozadí operačního systému Windows a automaticky zpracovává přijaté faktury doručené e-mailem. Instaluje se jako doplněk k aplikaci NET Genium ERP a vyžaduje technologickou schránku, do které dodavatelé zasílají faktury. Každý e-mail doručený do technologické schránky uloží i s přílohami do aplikace „Vytěžování faktur“ a z elektronických faktur rovnou založí dokumenty k vytěžení.

• Elektronické faktury se zpracují bez vytěžování – z každé vznikne dokument k vytěžení vyplněný jejími daty. Služba rozpozná ISDOC, UBL a CII podle evropské normy EN 16931 jako samostatné soubory i elektronickou fakturu vloženou v PDF (Factur-X, ZUGFeRD, ISDOC).
• PDF bez vložené elektronické faktury a obrázky se uloží jako přílohy e-mailu k dalšímu zpracování – ručnímu vytěžení nebo vytěžení službou Digitoo.
• Samostatnou elektronickou fakturu, která je kopií faktury v PDF téhož e-mailu, služba s tímto PDF spáruje, takže nevzniknou dva dokumenty.
• Najde-li služba v předmětu nebo v textu e-mailu číslo zakázky, propojí s ní e-mail i založené dokumenty.
• Každý založený dokument služba ihned zkontroluje, včetně upozornění na fakturu se stejným číslem od stejného dodavatele nebo na stejný soubor, který už byl zpracován.

2. Zpracování e-mailu

Každý e-mail se uloží jako záznam Přijatý e-mail s odesílatelem, příjemcem, předmětem, datem přijetí, textem a případně zakázkou. Přijaté e-maily jsou k dispozici na nahlížecích stránkách E-maily ke kontrole, E-maily z technologické schránky a Všechny e-maily aplikace „Vytěžování faktur“, založené dokumenty na stránkách Dokumenty ke kontrole a Všechny dokumenty.

Každá příloha e-mailu se uloží jako záznam Příloha e-mailu a podle svého typu se zpracuje takto:

Příloha	Zpracování
samostatná elektronická faktura – soubor .isdoc nebo .xml ve formátu ISDOC, UBL nebo CII	založí se dokument k vytěžení vyplněný daty faktury; příloha se označí jako „ISDOC“ a „Zpracováno“
PDF s vloženou elektronickou fakturou	založí se dokument k vytěžení vyplněný daty vložené faktury; příloha se označí jako „Zpracováno“
PDF bez vložené elektronické faktury, obrázek PNG nebo JPG	uloží se k vytěžení
obrázek menší než 50 kB	neuloží se – jde zpravidla o logo nebo obrázek v podpisu e-mailu
soubor .isdoc, který není platnou elektronickou fakturou, nebo PDF s poškozenou vloženou fakturou	uloží se a označí jako „Nevalidní ISDOC“; takovou přílohu nelze vytěžit
dokument Word nebo Excel (.docx, .doc, .odt, .xlsx)	uloží se a označí jako „Nevytěžitelný dokument“
příloha, kterou nelze přečíst (typicky zablokovaná antivirovým programem), a ostatní soubory	uloží se a označí jako „Zahodit“
připojený e-mail (.eml)	zkopíruje se do importního adresáře (viz kapitola 8) a zpracuje se jako samostatný e-mail; bez nastaveného importního adresáře se neuloží

V přehledu přijatých e-mailů je každý e-mail barevně odlišen podle svých příloh. Rozhoduje první podmínka, která platí:

• šedá – e-mail obsahuje přílohu, kterou nelze přečíst, neplatnou elektronickou fakturu nebo jiný soubor, který není elektronickou fakturou, PDF, obrázkem ani připojeným e-mailem
• červená – e-mail obsahuje PDF nebo obrázek bez vložené ani spárované elektronické faktury, který je potřeba vytěžit
• zelená – e-mail obsahuje PDF s vloženou nebo spárovanou elektronickou fakturou
• žlutá – ostatní e-maily, například e-mail bez příloh nebo jen se samostatnou elektronickou fakturou

Dokumenty založené z elektronické faktury mají v poli Vytěžení hodnotu „ISDOC“ bez ohledu na formát faktury – data pocházejí přímo z faktury. Údaje, pro které dokument nemá pole, se zapíší do jeho poznámky.

3. Párování PDF a samostatné elektronické faktury

Dodavatelé často posílají fakturu v PDF a vedle ní stejnou fakturu jako samostatnou elektronickou fakturu. Služba je proto v rámci jednoho e-mailu páruje:

• Samostatná elektronická faktura, která má stejné číslo faktury a stejné IČ nebo DIČ dodavatele jako elektronická faktura vložená v některém PDF téhož e-mailu, nový dokument nezaloží – uloží se jako příloha dokumentu vzniklého z PDF.
• Obsahuje-li e-mail jednu samostatnou elektronickou fakturu a jedno PDF nebo obrázek bez vložené faktury, spárují se vždy: vznikne jeden dokument, který má jako soubor PDF a data ze samostatné elektronické faktury.
• Obsahuje-li e-mail více samostatných elektronických faktur nebo více PDF, spáruje se elektronická faktura s tím PDF, v jehož textu se vyskytuje její číslo faktury jako samostatné slovo – jen tehdy, když je shoda jednoznačná v obou směrech. Nespárované soubory se zpracují samostatně.

4. Vyžadované soubory

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

• InvoiceService.exe
• InvoiceService.exe.config
• NETGeniumConnection.dll
• Aspose.PDF.dll

5. Technologická schránka

Nutnou podmínkou pro službu InvoiceService je existence technologické schránky, do které dodavatelé zasílají faktury. Obvyklým názvem je například „faktury@firma.cz“.

Přístup do technologické schránky se nastavuje buď v NET Geniu, nebo v konfiguračním souboru služby:

• V NET Geniu – v aplikaci „Vytěžování faktur“ na stránce Základní nastavení vytěžování faktur v polích POP3 Email, OAuth, POP3 Url, POP3 Name a POP3 Password. Je-li vyplněné pole POP3 Email, mají hodnoty z NET Genia přednost před konfiguračním souborem: e-mailová adresa a příznak OAuth se převezmou vždy, adresa serveru, přihlašovací jméno a heslo jen tehdy, když OAuth není zaškrtnuté a všechna tři pole jsou vyplněná.
• V konfiguračním souboru – klíči „pop3Email“, „pop3OAuth“, „pop3Url“, „pop3Name“ a „pop3Password“ (viz kapitola 9).

Služba stahuje e-maily jedním ze dvou způsobů:

• POP3 – jsou-li zadané adresa serveru, přihlašovací jméno i heslo. Se zapnutým OAuth se služba k serveru POP3 přihlašuje přístupovým tokenem Microsoft 365 místo hesla.
• Microsoft 365 (Microsoft Graph) – není-li zadaný server POP3, je zapnutý OAuth a v NET Geniu existuje konfigurační soubor „MicrosoftOAuth.json“ (viz kapitola 6). Služba stáhne zprávy schránky, jejíž adresa odpovídá zadané e-mailové adrese technologické schránky.

Jakmile služba v jednom běhu úspěšně zpracuje 500. e-mail, běh ukončí; zbytek zpracuje v dalším běhu. Všechny e-maily, které dorazí do technologické schránky, jsou po zpracování ze schránky smazány.

6. Konfigurace Microsoft Entra ID

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

6.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“

6.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"}}“
• Soubor sdílí i další služby, například PaymentService; existuje-li už, stačí doplnit oprávnění API podle předchozí kapitoly.

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

• InvoiceService ukládá průběh stahování a zpracování e-mailů včetně případných chyb do logového souboru „Logs\{yyyy-MM-dd}.log“ v adresáři služby.
• Server vrací chybu „Invalid client secret provided...“ – zkontrolovat, že je v „MicrosoftOAuth.json“ správná hodnota „client_secret“.
• Server vrací chybu „Application with identifier 'xxxxxxxxxx' was not found in the directory...“ – zkontrolovat, že je v „MicrosoftOAuth.json“ správná hodnota „tenant_id“.
• Server vrací chybu „ErrorAccessDenied“ – zkontrolovat, že má aplikace nastavená oprávnění API pro Microsoft Graph.

7. Zprávy, které nelze zpracovat

Skončí-li zpracování e-mailu chybou, e-mail zůstane v technologické schránce a služba se ho pokusí zpracovat znovu v dalším běhu. Po třech neúspěšných pokusech zkopíruje e-mail do podadresáře „Failed“ v adresáři služby a ze schránky ho smaže, aby opakovaně neselhával. Takový e-mail lze po odstranění příčiny zpracovat znovu jeho vložením do importního adresáře (viz kapitola 8).

Tentýž e-mail doručený do schránky vícekrát (stejný odesílatel, příjemci, předmět, datum a názvy příloh) služba zpracuje jen jednou, dokud běží bez restartu; další kopie jen zapíše do logu a ze schránky smaže.

8. Import e-mailových zpráv

InvoiceService 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 nastavit absolutní cestu k importnímu adresáři do konfiguračního souboru pod klíč „emlDir“; adresář služba v případě potřeby sama vytvoří. InvoiceService čte soubory v tomto adresáři, zpracovává je stejně jako e-maily stažené z technologické schránky a zpracované soubory přesune do zálohy stažených e-mailů (viz kapitola 11).

Do importního adresáře se ukládají také e-maily připojené jako příloha (.eml) k e-mailu v technologické schránce – zpracují se v dalším běhu služby.

9. Konfigurační soubor

Nastavení služby je v konfiguračním souboru „InvoiceService.exe.config“ ve stejném adresáři jako „InvoiceService.exe“. Pro obsluhu více instalací NET Genia lze vedle něj umístit další konfigurační XML soubory, jeden pro každou instalaci. 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="20:00" />
   <add key="stopTo" value="04:00" />

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

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

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

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

   <add key="emlDir" value="D:\Services\InvoiceService\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é služba InvoiceService nepracuje (nestahuje ani nezpracovává e-mailové zprávy)
• stopTo – koncový čas technologické pauzy ve formátu „HH:mm“, během které služba InvoiceService 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ě InvoiceService
• errorTo – e-mailová adresa, na kterou jsou zasílány notifikace o případných chybách ve službě InvoiceService
• 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 importnímu adresáři, ze kterého služba InvoiceService vyčítá a zpracovává „eml“ soubory
• ServiceName – volitelný název služby (viz kapitola 10)

Klíče „pop3Url“, „pop3Name“ a „pop3Password“ se vyplňují jen pro stahování přes POP3; pro stahování přes Microsoft 365 se vynechají.

10. Instalace služby

• InvoiceService je služba, která běží na pozadí operačního systému Windows, a automaticky se aktivuje a stahuje e-maily každé 3 minuty. Nestačí tedy prosté spuštění programu „InvoiceService.exe“, ale je nutná instalace služby pomocí zástupce „InvoiceService - user.lnk“. Zástupce „InvoiceService - user.lnk“ vznikne automaticky spuštěním programu „InvoiceService.exe“.
• Zástupce „InvoiceService - 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 „InvoiceService.exe.config“. Není-li parametr uveden, použije se výchozí název „InvoiceService“.
• Odinstalaci programu provedete také spuštěním programu „InvoiceService.exe“ a kliknutím na tlačítko „Uninstall“.

11. 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 „InvoiceService.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. Zálohy starší než 6 měsíců služba sama maže, logové soubory starší než jeden rok rovněž.

• Příklad:

D:\Services\InvoiceService\POP3Downloads\2026-10-23\154C463D-386A-4B61-BF0D-6B2CD91A1BCB.eml