InvoiceService web guide

1. General information

InvoiceService is a service that runs in the background of the Windows operating system and automatically processes incoming invoices delivered by e-mail. It is installed as an add-on to the NET Genium ERP application and requires a technology mailbox to which suppliers send invoices. It saves every e-mail delivered to the technology mailbox, including its attachments, to the “Extraction of invoices” application, and creates documents for extraction directly from electronic invoices.

Electronic invoices are processed without extraction – each one creates a document for extraction filled in with its data. The service recognizes ISDOC, UBL and CII according to the European standard EN 16931 as standalone files as well as an electronic invoice embedded in a PDF (Factur-X, ZUGFeRD, ISDOC).
PDFs without an embedded electronic invoice and images are saved as e-mail attachments for further processing – manual extraction or extraction by the Digitoo service.
A standalone electronic invoice that is a copy of the invoice in a PDF of the same e-mail is paired with that PDF, so two documents are not created.
If the service finds a contract number in the subject or in the text of the e-mail, it links the e-mail and the created documents to the contract.
The service checks every created document immediately, including a warning about an invoice with the same number from the same supplier or about the same file that has already been processed.

2. Processing an e-mail

Every e-mail is saved as a Received e-mail record with the sender, the recipient, the subject, the date of receipt, the text and possibly the contract. Received e-mails are available on the Pending e-mails, E-mails from extraction inbox and All e-mails view pages of the “Extraction of invoices” application, created documents on the Pending documents and All documents pages.

Every attachment of the e-mail is saved as an Email attachment record and processed according to its type as follows:

Attachment	Processing
standalone electronic invoice – an .isdoc or .xml file in the ISDOC, UBL or CII format	a document for extraction filled in with the data of the invoice is created; the attachment is marked as “ISDOC” and “Processed”
PDF with an embedded electronic invoice	a document for extraction filled in with the data of the embedded invoice is created; the attachment is marked as “Processed”
PDF without an embedded electronic invoice, PNG or JPG image	saved for extraction
image smaller than 50 kB	not saved – it is usually a logo or an image in the e-mail signature
.isdoc file that is not a valid electronic invoice, or a PDF with a damaged embedded invoice	saved and marked as “Invalid ISDOC”; such an attachment cannot be extracted
Word or Excel document (.docx, .doc, .odt, .xlsx)	saved and marked as “Unextractable document”
attachment that cannot be read (typically blocked by an antivirus program) and other files	saved and marked as “Discard”
attached e-mail (.eml)	copied to the import directory (see chapter 8) and processed as a separate e-mail; without an import directory set, it is not saved

In the overview of received e-mails, each e-mail is distinguished by color according to its attachments. The first condition that applies decides:

gray – the e-mail contains an attachment that cannot be read, an invalid electronic invoice or another file that is not an electronic invoice, a PDF, an image or an attached e-mail
red – the e-mail contains a PDF or an image without an embedded or paired electronic invoice that needs to be extracted
green – the e-mail contains a PDF with an embedded or paired electronic invoice
yellow – other e-mails, for example an e-mail without attachments or only with a standalone electronic invoice

Documents created from an electronic invoice have the value “ISDOC” in the Extraction field regardless of the format of the invoice – the data come directly from the invoice. Data the document has no field for are written to its comment.

3. Pairing a PDF with a standalone electronic invoice

Suppliers often send an invoice as a PDF and the same invoice as a standalone electronic invoice next to it. The service therefore pairs them within one e-mail:

A standalone electronic invoice that has the same invoice number and the same identification number or VAT number of the supplier as an electronic invoice embedded in a PDF of the same e-mail does not create a new document – it is saved as an attachment of the document created from the PDF.
If an e-mail contains one standalone electronic invoice and one PDF or image without an embedded invoice, they are always paired: one document is created, which has the PDF as its file and the data from the standalone electronic invoice.
If an e-mail contains several standalone electronic invoices or several PDFs, an electronic invoice is paired with the PDF whose text contains its invoice number as a separate word – only when the match is unambiguous in both directions. Unpaired files are processed separately.

4. Required files

For InvoiceService to work, the following files must be in its directory:

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

5. Technology mailbox

A necessary condition for the InvoiceService is the existence of a technology mailbox to which suppliers send invoices. A usual name is, for example, “invoices@company.com”.

Access to the technology mailbox is set either in NET Genium or in the configuration file of the service:

In NET Genium – in the “Extraction of invoices” application on the Basic settings for invoice extraction page in the POP3 Email, OAuth, POP3 Url, POP3 Name and POP3 Password fields. If the POP3 Email field is filled in, the values from NET Genium take precedence over the configuration file: the e-mail address and the OAuth flag are always taken over, the server address, login name and password only when OAuth is not checked and all three fields are filled in.
In the configuration file – with the “pop3Email”, “pop3OAuth”, “pop3Url”, “pop3Name” and “pop3Password” keys (see chapter 9).

The service downloads e-mails in one of two ways:

POP3 – if the server address, login name and password are all specified. With OAuth enabled, the service signs in to the POP3 server with a Microsoft 365 access token instead of the password.
Microsoft 365 (Microsoft Graph) – if no POP3 server is specified, OAuth is enabled and the configuration file “MicrosoftOAuth.json” exists in NET Genium (see chapter 6). The service downloads the messages of the mailbox whose address matches the specified e-mail address of the technology mailbox.

As soon as the service successfully processes the 500th e-mail in one run, it ends the run; it processes the rest in the next run. All e-mail messages that arrive in the technology mailbox are deleted from the mailbox after processing.

6. Microsoft Entra ID configuration

InvoiceService requires additional manual configuration of Microsoft Entra ID (formerly Azure Active Directory) when it downloads e-mails from a technology mailbox operated using Microsoft cloud services.

6.1. Configuration on the “https://portal.azure.com” portal

Registration of the “NET Genium” application on the https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps web page
- Czech: portal.azure.com / Registrace aplikací
- English: portal.azure.com / App registrations
- NET Genium as the application name
- Finding the Application (client) ID, which is created automatically when the application is registered
  - Czech: ID aplikace (klienta)
  - English: Application (client) ID
- Finding the Directory (tenant) ID, which is created automatically when the application is registered
  - Czech: ID adresáře (tenanta)
  - English: Directory (tenant) ID
- Creating a client secret
  - Czech: portal.azure.com / Registrace aplikací / NET Genium / Certifikáty a tajné kódy / Nový tajný kód klienta
  - English: portal.azure.com / App registrations / NET Genium / Certificates & secrets / New client secret
- Setting API permissions for Microsoft Graph
  - Czech: portal.azure.com / Registrace aplikací / NET Genium / Oprávnění rozhraní API / Přidat oprávnění / Microsoft Graph
  - English: portal.azure.com / App registrations / NET Genium / API permissions / Add a permission / Microsoft Graph
  - API name “Microsoft Graph – Mail.ReadWrite”, type “Application”
  - API name “Microsoft Graph – User.Read.All”, type “Application”

6.2. NET Genium configuration

Creating the configuration file “NETGenium\Config\MicrosoftOAuth.json”
- Set the content of the file to: “{"web":{"client_id":"Application (client) ID","tenant_id":"Directory (tenant) ID","auth_uri":"https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize","token_uri":"https://login.microsoftonline.com/organizations/oauth2/v2.0/token","client_secret":"client secret"}}”
The file is shared by other services as well, for example PaymentService; if it already exists, it is enough to add the API permissions according to the previous chapter.

6.3. Troubleshooting errors or non-functional downloading of e-mails

InvoiceService saves the progress of downloading and processing e-mails, including any errors, to the “Logs\{yyyy-MM-dd}.log” log file in the directory of the service.
The server returns the error “Invalid client secret provided...” – check that the “client_secret” value in “MicrosoftOAuth.json” is correct.
The server returns the error “Application with identifier 'xxxxxxxxxx' was not found in the directory...” – check that the “tenant_id” value in “MicrosoftOAuth.json” is correct.
The server returns the error “ErrorAccessDenied” – check that the application has the API permissions for Microsoft Graph set.

7. Messages that cannot be processed

If processing of an e-mail ends with an error, the e-mail stays in the technology mailbox and the service tries to process it again in the next run. After three failed attempts, it copies the e-mail to the “Failed” subdirectory in the directory of the service and deletes it from the mailbox, so that it does not fail repeatedly. Once the cause is removed, such an e-mail can be processed again by placing it in the import directory (see chapter 8).

The same e-mail delivered to the mailbox several times (the same sender, recipients, subject, date and attachment names) is processed only once while the service runs without a restart; further copies are only written to the log and deleted from the mailbox.

8. Importing e-mail messages

InvoiceService can import existing “eml” files, which are e-mail messages saved in their original format. For this purpose, the absolute path to the import directory must be set in the configuration file under the “emlDir” key; the service creates the directory itself if necessary. InvoiceService reads the files in this directory, processes them in the same way as e-mails downloaded from the technology mailbox and moves the processed files to the backup of downloaded e-mails (see chapter 11).

E-mails attached (.eml) to an e-mail in the technology mailbox are also saved to the import directory – they are processed in the next run of the service.

9. Configuration file

The settings of the service are in the “InvoiceService.exe.config” configuration file in the same directory as “InvoiceService.exe”. To serve several NET Genium installations, further XML configuration files, one for each installation, can be placed next to it. Example configuration file:

<?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@company.com" />
   <add key="errorTo" value="support@netgenium.com" />

   <add key="pop3Email" value="invoices@company.com" />
   <add key="pop3OAuth" value="true" />

   <add key="pop3Url" value="pop3.company.com" />
   <add key="pop3Name" value="invoices@company.com" />
   <add key="pop3Password" value="pop3password" />

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

  </appSettings>
</configuration>

rootPath – the absolute path on the disk to the NET Genium directory
stopFrom – the start time of the technology pause in the format “HH:mm”, during which the InvoiceService does not work (it neither downloads nor processes e-mail messages)
stopTo – the end time of the technology pause in the format “HH:mm”, during which the InvoiceService does not work
smtpServer – the address of the outgoing mail server
errorFrom – e-mail address from which notifications about possible errors in the InvoiceService are sent
errorTo – e-mail address to which notifications about possible errors in the InvoiceService are sent
pop3Email – e-mail address of the technology mailbox
pop3OAuth – flag indicating whether enhanced OAuth2 security should be used for authentication together with the configuration file “MicrosoftOAuth.json”
pop3Url – the address of the incoming mail server, optionally with a port number in the form “server name:port number” (the default port is 110); a secure SSL connection is used only on port 995 (for example “pop3.company.com:995”), on any other port the service connects without SSL
pop3Name – login name to the technology mailbox
pop3Password – the password to the technology mailbox
emlDir – the absolute path on the disk to the import directory from which the InvoiceService reads and processes the “eml” files
ServiceName – optional name of the service (see chapter 10)

The “pop3Url”, “pop3Name” and “pop3Password” keys are filled in only for downloading via POP3; for downloading via Microsoft 365 they are omitted.

10. Installation of the service

InvoiceService is a service that runs in the background of the Windows operating system and automatically activates and downloads e-mails every 3 minutes. Therefore, it is not enough to simply run the “InvoiceService.exe” program, but it is necessary to install the service using the “InvoiceService - user.lnk” shortcut. The “InvoiceService - user.lnk” shortcut is created automatically by running the “InvoiceService.exe” program.
The “InvoiceService - user.lnk” shortcut opens the service installation dialog. In it, Startup mode needs to be set to “Automatic” and Account to “LocalSystem”; the installation of the service is completed with the “Install” button.
The name under which the service is installed and displayed in the Windows operating system service list can be changed using the optional “ServiceName” parameter in the main service configuration file “InvoiceService.exe.config”. If the parameter is not specified, the default name “InvoiceService” is used.
You can also uninstall the program by running the “InvoiceService.exe” program and clicking the “Uninstall” button.

11. Backing up downloaded e-mail messages

Copies of all e-mail messages delivered to the technology mailbox are automatically saved in the “POP3Downloads\yyyy-MM-dd” subdirectory, which is located in the same directory as “InvoiceService.exe”. E-mail messages are stored under a random name (GUID.eml) and are placed in a subdirectory whose name identifies the day the e-mail message was downloaded. The service deletes backups older than 6 months itself, as well as log files older than one year.

Example:

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