PDA Files
Minimal approach integration using text files
English 🇬🇧
Slovensky 🇸🇰
Integration via PDA files is an alternative to integration via the HTTP WEB API interface. Compared to HTTP WEB API integration, it is faster to implement but limited in its possibilities.
The connection between your external application (eshop, etc.) and the PORTOS system should be handled via PDA files if all below apply:
- the connection is only related to the creation or printing of the receipt and there is no need to transfer other data.
- the external application does not need to obtain any additional information from the system (e.g. list of goods, change stock balances, etc.).
- an external application can create a text file directly on the computer running PORTOS.
If all the mentioned points meet your needs, integration via PDA files may be the solution for you. On the contrary, if you need a more complex exchange of information between your application and the PORTOS system, integration via the HTTP WEB API interface will be the right choice, as it provides comprehensive options and has no limitations.
Integrácia cez PDA súbory je alternatíva k plnohodnotnej integrácii cez HTTP WEB API rozhranie. Oproti HTTP WEB API integrácii je rýchlejšia na realizáciu ale limitovaná vo svojich možnostiach.
Prepojenie medzi Vašou externou aplikáciou (eshop a podobne) a systémom PORTOS je vhodné riešiť cez PDA súbory, ak:
- sa prepojenie týka výhradne vytvorenia alebo vytlačenia pokladničného dokladu a nie je potrebné prenášať iné údaje.
- externá aplikácia nepotrebuje získavať zo systému žiadne ďalšie informácie (napr. zoznam tovarov, meniť skladové zostatky atď.).
- externá aplikácia dokáže vytvoriť textový súbor priamo na počítači, na ktorom beží systém PORTOS.
Ak všetky uvedené body vyhovujú Vašim potrebám, integrácia cez PDA súbory môže byť riešením pre Vás. Naopak, ak potrebujete komplexnejšiu výmenu informácii medzi vašou aplikáciou a systémom PORTOS, integrácia cez HTTP WEB API rozhranie bude tou správnou voľbou, poskytuje komplexné možnosti a nemá žiadne obmedzenia.
The integration is based on one-way (from external application to PORTOS) exchange of files (with
.PDA
extension) in specified directory (usually C:/POS
). PORTOS will observe this directory and process file content of all files with matching extension with goal to create or print receipt.- File extension: must be
*.pda
or*.PDA
. - Name: unique name, generated by external application. We recommend to use timestamp or ID related to transaction.
- File content: formatted as stated in this documentation.
Once file is processed successfuly (and receipt is printed), file is deleted by PORTOS.
When any error occurs during file processing, file is moved to "unprocessed files directory" (usually
C:/POS/FAILED
, can be configured). You can retry file processing moving file from this directory back to input directory.Error logs are available in API working directory (usually
C:/ProgramData/NineDigit/PORTOS/API/Logs
). When contacting technical support, please attach the log file as well.
File content consists of various types of lines. Type of line is specified by first character of each line.
First character | Description | Required |
---|---|---|
I , A or S | Yes, at least one | |
D | No | |
F | No | |
L | No |
Each receipt item is represented by separate line containing 77+ characters and has following format:
Name | Comment | Column | Length | Required |
---|---|---|---|---|
Operation type | Single character I . You can also specify A for addition (positive item), or S for storno (negative item). For storno items, quantity field will be multiplied by minus one. | 0 | 1 | Yes |
Cashier user name | Optional user name of cashier (limited to 3 characters). If specified, user account with specified user name must exists in PORTOS. If not specified (file line contains 3 spaces), receipt will be printed using system-created "Camarero" user. | 1-3 | 3 | No |
Receipt name | Name of receipt (will be also printed on receipt). If not specified (file line contains 12 spaces), default value will be used. | 4-15 | 12 | No |
Product code | Numbers only. References to code of product (PLU) defined in PORTOS. If not specified (zero value or 13 spaces), no product will be looked up in PORTOS - this is what we name as "anonymous product". | 16-28 | 13 | No |
Quantity | Numbers only. Value is transfered as integer, s 100 means one unit (when quantity precision is set to default value, 2 ). Note: quantity precision can be configured up to 3 digits so value 1000 would represent one unit. | 29-34 | 6 | Yes |
Unit price including VAT | Numbers only. Value is transfered as integer, s 100 means one currency unit (when quantity precision is set to default value, 2 ). Note: unit price precision can be configured up to 6 digits so value 1000000 would represent one currency unit. | 35-41 | 7 | Yes |
Customer card serial number | Unique customer card serial number (must be defined in PORTOS). Use zeroes or spaces to indicate that no customer card is associated with purchase. | 42-49 | 8 | No |
Discount rate | Receipt item discount rate, transfered as integer. Value 03333 represents 33.33% discount for this ticket item. Maximum value is 10000 (100.00%). User zerues or spaces to indicate that no discount is associated with given ticket item. | 50-54 | 5 | No |
Payment name | Note: this value is deprecated, please use 20 space characters. | 55-74 | 20 | No |
Payment type | If receipt should be printed, specify payment type identifier (value from 1 to 10). Usually, 1 means cash payment, 2 means card payment.
To indicate that ticket should not be closed (will be imported to PORTOS as opened ticket), use two spaces or zeroes. | 75-76 | 2 | No |
VAT category | VAT category identifier with value from 1 to 5 . Usually 1 is associated with basic vat rate, 2 with reduced vat rate. Other categories are associated with zero vat rate. Value will be only used for anonymous products. If not specified (by using zero or space character), value from configuration will be used. | 77 | 1 | No |
Unit | Quantity unit used for anonymous products only. If not specified (by using zero or space character), value from configuration will be used. | 78-80 | 3 | No |
Product name | Name of product (with no length limitation), user for anonymous products only. | 81-* | * | For anonymous products only |
Optional footer text that will be printed at the end of receipt. For multiline footers, use multiple lines with D character as prefix.
Name | Comment | Column | Length |
---|---|---|---|
Operation type | Single character D | 0 | 1 |
Footer text | Custom text with unlimited length. Note: receipt printer usually prints 42 characters per single line. | 1-* | * |
Optional name of fiscal printer, on which receipt will be printed. If not specified, value configured in PORTOS will be used.
Name | Comment | Column | Length |
---|---|---|---|
Operation type | Single character F | 0 | 1 |
Fiscal name | Name of fiscal printer | 1-* | * |
Optional name of table and zone, separated by
@
character.E.g.: Table named
B01
in Bar
zone.LB01@Bar
- First line: Contains ticket item referencing product with code 1 (product with given code must exist in PORTOS). When no product with code 1 is defined in PORTOS, PDA file processing would fail. Quantity is set to one, price to 3.50 and discount rate to 33.33%. Payment type is set to 1, VAT category as well to 1.
- Second line: contains “anonymous product” – product that is not created in PORTOS. To indicate “anonymous product” Product code (PLU) must be set to zero, product name must be specified. Quantity is set to one, price to 3.50 and discount rate to 33.33%. Payment type is set to 1, VAT category to 1, unit to 'x'. Product name is "Product name goes here".
- Third and fourth line: Optional multiline footer printed at the end of the receipt.
- Fifth line: Optional name of fiscal printer (for example “eKasa”) on which receipt printing should be performed. Fiscal printers are defined in PORTOS.
A999Receipt name 1 100 350 03333 011
A999Receipt name 0 100 350 03333 011 xProduct name goes here
DThis is receipt footer.
DThis is another line for receipt footer
LB01@Bar
FeKasa
example_file.pda
259B
Binary
- MAJOR version: incompatible API changes are introduced.
- MINOR version: functionality is added in a backward compatible manner.
- Added:
- Ticket location support added. PORTOS API v4.0.46 required.
- Added:
- Documentation for V1 processor supported in PORTOS API v4.0.31.