ErpNet.FP
ErpNet.FP is a light-weight cross-platform Http server facilitating printing to fiscal printers through simple JSON Api.
Install / Use
/learn @erpnet/ErpNet.FPREADME
ErpNet.FP
ErpNet.FP is a light-weight multi-platform Http server facilitating printing to fiscal printers through simple JSON Api. The library provides methods to detect, get status, print receipts, reports and other documents to fiscal printers.
The ErpNet.FP http server provides a REST API with JSON input/output, which prints documents transactionally and returns result status.
The http server receives input through the REST API and uses different transports to communicate with the fiscal printers. The transports include:
- COM serial connection
- Bluetooth connection through mapping to COM port
- TCP/IP
- etc.
Shortcut to Download
The Net.FP Protocol
All communication with the ErpNet.FP print server is based on the Net.FP (Net Fiscal Protocol).
Requests
The print server accepts documents for printing, using JSON based protocol. For example, this would print the specified receipt to dt517985, which is the printerId of one of the detected printers, listed with GET /printers (see below for printerId explanation):
POST /printers/dt517985/receipt
{
"uniqueSaleNumber": "DT279013-0001-0000001",
"items": [
{
"text": "Cheese",
"quantity": 1,
"unitPrice": 12,
"taxGroup": 2
},
{
"type": "comment",
"text": "Additional comment to the cheese..."
},
{
"text": "Milk",
"quantity": 2,
"unitPrice": 10,
"taxGroup": 2,
"priceModifierValue": 10,
"priceModifierType": "discount-percent"
},
{
"type": "footer-comment",
"text": "YOU ARE WELCOME!"
}
],
"payments": [
{
"amount": 30,
"paymentType": "cash"
}
]
}
For More Information
For more information, see the full documentation of the protocol.
Response - Interpreting The Results
The most important result is the "ok" field. It contains "true" when the POST operation was successful, otherwise - "false". If there was error, "ok" would be "false".
If "ok"="false", it is guaranteed, that at least one message of type "error" would be present.
The error and warning messages have standardized codes across all manufacturers. The standard error and warning codes are listed in the Error and Warning Codes file.
The standard error codes are a subset of all manufacturer codes and flags. In some cases, the specific manufacturer codes, flags and messages could contain more detailed information. The manufacturer code, when available, is contained in the "originalCode" field. The problem with using the manufacturer codes is that they are different for each manufacturer. For some manufacturers they are not even present (there might be just some status flags). The manufacturer codes can even change between revisions of printers of the same manufacturer. The standardized error and warning codes are guaranteed to be the same across all manufacturers and printer versions. Messages with "type": "info", have no codes, because they cannot be standardized.
Example Return JSON (No Problems) after printing receipt:
{
"ok": "true",
"messages": [
{
"type": "info",
"text": "Serial number and number of FM are set"
},
{
"type": "info",
"text": "FM is formatted"
}
],
"receiptNumber": "0000085",
"receiptDateTime": "2019-05-17T13:55:18",
"receiptAmount": 30,
"fiscalMemorySerialNumber": "02517985"
}
Example Return JSON (Warning) while getting the status:
{
"ok": "true",
"messages": [
{
"type": "warning",
"code": "W201",
"text": "The fiscal memory almost full"
},
{
"type": "info",
"text": "Serial number and number of FM are set"
},
{
"type": "info",
"text": "FM is formatted"
}
],
"deviceDateTime": "2019-05-10T15:50:00"
}
Example Return JSON (Error):
{
"ok": "false",
"messages": [
{
"type": "error",
"code": "E201",
"text": "The fiscal memory is full"
},
{
"type": "info",
"text": "Serial number and number of FM are set"
},
{
"type": "info",
"text": "FM is formatted"
}
]
}
Download
Eager to try? You can list and [download the binaries for ErpNet.FP.Server]:
Windows 32/64 Service Installer (.MSI) ** New **
- Prerequisites for ErpNet.FP on Windows.
- There is no need for .Net installation.
- Everything that is needed is included in the MSI installer.
Download: [Installer for Windows 32/64]
The Windows installer setups or updates the ErpNet.FP Fiscal Print Server on a Windows 32 or 64 bit OS. The installer unpacks and installs a Windows service, called "ErpNet.FP". There is no UI, but when the service is running in the default configuration, you can browse the Admin page at http://localhost:8001.
Windows 32/64 bit, folder install
- Prerequisites for ErpNet.FP on Windows.
- There is no need for .Net installation.
- Everything that is needed is included in the Zip files below.
Download 32 bit (x86): [win-x86.zip - Windows 32 bit]
Download 64 bit (x64): [win-x64.zip - Windows 64 bit]
Download and unzip the file in a folder. Inside the folder you will find executable file: ErpNet.FP.Server.exe. To start the printing service, run ErpNet.FP.Server.exe, or register the executable as a Windows service. When the service is running in the default configuration, you can browse the Admin page at http://localhost:8001.
OSX 10.10 and up, 64 bit folder install
Download 64 bit - [osx-x64.zip - macOS] - You can download and unzip the server in a folder.
Inside the unzipped folder, run it from console/terminal with:
./ErpNet.FP.Server
When the service is running in the default configuration, you can browse the Admin page at http://localhost:8001.
Linux 64 bit, folder install
Download 64 bit - [linux-x64.zip - Linux x64] - You can download and unzip the server.
Because of the serial ports default permissions, run it from sudoer, with sudo, or in the root user context. For convenience, create a systemd service config file, get more info how to do it here [Systemd: Service File Examples]. The other way is to run it from non-root user, but that user should have permissions to read and write to serial ports. When the service is running in the default configuration, you can browse the Admin page at http://localhost:8001.
Linux-Arm 64 bit, folder install
Download 64 bit - [linux-arm.zip - Linux Arm] - You can download and unzip the server.
This version is compatible with Raspberry PI OS, Raspbian, and 64 bit Arm devices like Raspberry PI 3B+, Raspberry PI 2 and up. Because of the serial ports default permissions, run it from sudoer, with sudo, or in the root user context. For convenience, create a systemd service config file, get more info how to do it here [Systemd - Raspberry Pi Documentation]. The other way is to run it from non-root user, but that user should have permissions to read and write to serial ports. When the service is running in the default configuration, you can browse the Admin page at http://localhost:8001.
Important: The requirement for running ARM CPUs is to support at least the vfpv4d32 floating point feature. This is why we prefer to support only 64 bit CPUs, because they support that feature and more... For reference see: Issue 17043 at dotnet/coreclr.
Debug information
For debugging purposes, there is a link to debug.log and it's folder in the Admin page. It contains debug information for every event that occured while using the service.
Server Configuration
The server configuration options are located in a file, called "appsettings.json". For more information, see Configuration. It is recommended that you use the Admin page, or through /service API to edit the settings in this file rather than edit it directly.
Fiscal Printer Setup
Most fiscal printers or cash register should be in "Fiscal Printer" mode in order to accept commands from the PC through the serial interface. Refer to your printer manual how to setup the fiscal printer mode.
The following non-comprehensive article contains the setup procedure for some fiscal printers:
Concepts
Printer Id
Each printer is identified by its printerId. Although the library consumer does not need to know the exact specifics of the algorithm for generating the printerId, they are provided here for completeness:
-
For locally connected printers, the printerId is the printer serial number. For example: "dy448967"
-
If a local printer is connected through multiple transports (for example: both COM and BT), the id for each next transport connection is assigned a consecutive number. For example: "dy448967_1" Note: The algorithm runs always in the same order. Unless transports are changed, the id would remain constant. However, it is advised to always use the default, non-numeric id.
-
For network printers, the printerId is provided in the configuration file. For example: "FP_Room1"
Printer Uri
When a printer is detected, the http server saves something, called printer Uri. The Uri contains the connection informatio
