PDA Files

Minimal approach integration using text files

Introduction

English 🇬🇧

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.

When is it appropriate to choose integration via PDA files instead of integration via HTTP WEB API?

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.

Slovensky 🇸🇰

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.

Kedy je vhodné zvoliť integráciu cez PDA súbory miesto integrácie cez HTTP WEB API?

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.

How the integration works

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 requirements

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

Error handling

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

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	Ticket item (product)	Yes, at least one
D	Footer text	No
F	Fiscal name	No
L	Ticket location	No

Ticket item line

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

Footer text line

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-*	*

Fiscal name line

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-*	*

Ticket location

Optional name of table and zone, separated by @ character.

E.g.: Table named B01 in Bar zone.

LB01@Bar

File example

• 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

259B

example_file.pda

Versioning

This API uses semantic versioning. Given a version number MAJOR.MINOR, increment the:

• MAJOR version: incompatible API changes are introduced.

• MINOR version: functionality is added in a backward compatible manner.

Changelog

Version 1.1 (2023-07-10)

• Added:

  • Ticket location support added. PORTOS API v4.0.46 required.

Version 1.0 (2023-01-12)

• Added:

  • Documentation for V1 processor supported in PORTOS API v4.0.31.