# Introduction Welcome to the [PORTOS Cash register](https://portos.sk) system developer guide. This documentation serves as a reference for the REST API server, which is an integral part of the PORTOS Cash Register solution developed by Nine Digit s.r.o. The server facilitates communication with hardware devices such as order printers for food orders and fiscal printers for receipt printing. By utilizing the endpoints outlined in this guide, the client is relieved of the need to directly communicate with hardware components or external services. This comprehensive API coverage encompasses the entire sales process, from food ordering to receipt printing. {% hint style="info" %} #### Looking for the user manual? See [docs.portos.sk](https://docs.portos.sk/). The user manual provides detailed instructions and guidance in the Slovak language on how to use the PORTOS Cash Register system. {% endhint %} # Glossary Following table contains terms used in this documentation.

Term	Meaning
Term	Meaning
`user`	Cashier (when using cash register application, or manager using admin application).
`device`	Cash register (either stationary application for desktop operating systems, or mobile application for mobile operating systems such as android or iOS) or any other application within PORTOS ecosystem.
`plu`	Merchandise article.
`ticket`	Food order. Until order is paid, food order is addressed as opened ticket. After order is paid (and receipt is printed), food order is addressed as closed ticket.
`order`	Food preparation request, that is created after articles are added to ticket. Example: user (cashier), based on customers request, adds plu article(s) to ticket, which leads to order creation, that is being handled by cook.
`order processing`	Process of printing/indicating food orders (to kitchen printers or kitchen displays)
`ticket closing`	Process of printing fiscal receipt (transition from opened ticket to closed ticket).
`fiscal device`	Receipt printer that prints cash register receipts (part of ticket closing procedure).
`order endpoint`	Kitchen printer or kitchen tablet. An device/application, usually located in kitchen, that handles food orders.

# HTTP Status codes List of all HTTP status codes used by API ### Successful status codes

HTTP Status		Description
200	OK	Operation was successful. Payload is located in response body.
201	Created	Create operation was successful. Payload is located in response body.
202	Accepted	Operation request is accepted. The task will continue in background.
204	No Content	Operation was successful. There is no payload in response body.

### Error status codes Statuses in range 400-499 are considered as client errors, range 500-599 represents server errors.

HTTP Status		Error model	Description
400	Bad Request	`PortosValidationProblemDetails`	Request is invalid or contains invalid data.
401	Unauthorized	`ProblemDetails`	User is not logged in, or user authentication has failed (invalid credentials).
403	Forbidden	`ProblemDetails`	User is logged in but does not have sufficient access rights, or operation itself is forbidden.
404	Not found	`ProblemDetails`	Resource is not found.
423	Locked	`ProblemDetails`	Resource is locked (temporarily used by another part of application).
500	Internal server error	`ProblemDetails`	Error occured on server side.

# Error models This article describes API error formats Based on response [HTTP status code](/http-status-codes), one of following error models are returned in response body. ## ProblemDetails A machine-readable format for specifying errors in HTTP API responses based on .

Name	Type	Description
`type`	`string?`	A URI reference [RFC3986] that identifies the problem type.
`title`	`string?`	A short, human-readable summary of the problem type.
`status`	`int?`	The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
`detail`	`string?`	A human-readable explanation specific to this occurrence of the problem.
`instance`	`string?`	A request URI path.
`traceId`	`string?`	Unique identifier to represent this request in trace logs.
`errorCode`	`int?`	API error code, if applicable.
`resource`	`ResourceInfo?`	Information about resource present in request. Available when errorCode is 6 (Version mismatch)

## PortosValidationProblemDetails This class inherits all properties from [`ProblemDetails`](#problemdetails), and adds properties listed below:

Name	Type	Description
`errors`	`PortosValidationProblemDetailsError[]`	Collection of errors. Each element represents one broken validation rule.

## PortosValidationProblemDetailsError

Name	Type	Description
`memberName`	`string`	Property name.
`message`	`string`	Message that describes error.
`code`	`string?`	One of validation constraints, if applicable.

## ResourceInfo

Name	Type	Description
`name`	`string`	Resource name
`id`	`string`	Unique resource identifier
`version`	`int?`	Resource version

# Error codes List of error codes that are specified in `errorCode` property of [ProblemDetails](/error-models#problemdetails) class. ## 1 - Unautenthicated User is not logged in. Please authenticate and repeat the action. ## 2 - Unauthorized User is not authorized to perform specific action. Additional rights must be granted to the user for successful action execution. ## 3 - ValidationFailed One or more validation rules were broken. Action should not be repeated unless request is modified or another resource that action relies on is changed. ## 4 - LicenseExpired License is valid, but expired. License must be extended before repeating the action. ## 5 - ResourceLocked Resource is temporarly locked by another session or instance. Action can be invoked again later. ## 6 - ResourceVersionMismatch Resource version mismatch. The error occurs especially if the resource is stored on the API in a newer version than the version specified in the request. # Validation constraints List of validation constraints that are specified in `code` property of [`PortosValidationProblemDetailsError`](/error-models#portosvalidationproblemdetailserror). ## 1 - Required Property is required, but was not specified. ## 2 - Unique Property value must be unique. # Resource names List of system-defined resource names: * `articleCategories` * `companies` * `currencies` * `customers` * `dailySalesReports` * `devices` * `fiscals` * `modifiers` * `orderEndpoints` * `orders` * `paymentTypes` * `plus` * `roles` * `stocks` * `stockTakings` * `stockTransferNumberings` * `stockTransfers` * `tickets` * `users` * `vats` * `zones` # User rights Each functionality provided by API has one of following access restrictions: * **None**: Resource is whitelisted during authorization, and no authorization is required to access the resource. * **Authorized** : Authenticated is required to access resource, but no specific user right is required. Unauthenticated users are forbidden to invoke given action. * **Right(s) required**: User must be authorized and must have specific "user right(s)" assigned to access the resource. Note that specific payloads may modify rights that are required to perform given action. Example: user may update ticket with user right `ticketUpdate`. But if provided ticket contains item quantity decrease, API requires additional `storno` right. ## Rights list * Api key * `apiKeyCreate` * `apiKeyUpdate` * `apiKeyDelete` * Article category * `articleCategoryCreate` * `articleCategoryUpdate` * `articleCategoryDelete` * Currency * `currencyCreate` * `currencyUpdate` * `currencyDelete` * Customer * `customerCreate` * `customerUpdate` * `customerDelete` * `customerSetCredit` * `customerSetDiscount` * Company * `companyCreate` * `companyUpdate` * `companyDelete` * Daily sales report * `dsrCreate` * `dsrUpdate` * `dsrDelete` * `dsrCloseManually` * Device * `deviceCreate` * `deviceUpdate` * `deviceDelete` * Fiscal * `fiscalCreate` * `fiscalUpdate` * `fiscalDelete` * `fiscalOpenDrawer` * `fiscalCashTransfer` * `fiscalPrintRecordCopy` * `summaryIntervalSalesReport` * `detailedIntervalSalesReport` * `overviewSalesReport` * `doDailySalesReport` * `fiscalPrintDailySalesReportCopy` * `printNonfiscalRecord` * License * `licenseGet` * `licenseActivate` * Modifiers * `modifierCreate` * `modifierUpdate` * `modifierDelete` * Order endpoints * `orderEndpointCreate` * `orderEndpointUpdate` * `orderEndpointDelete` * Orders * `orderUpdate` * `orderDelete` * `orderProcess` * Payment types * `paymentTypeCreate` * `paymentTypeUpdate` * `paymentTypeDelete` * PLUs * `pluCreate` * `pluUpdate` * `pluDelete` * Roles * `roleCreate` * `roleUpdate` * `roleDelete` * Stats * `stats` * `statsCurrent` * `statsPlus` * `statsPrint` * `statsTickets` * `statsTicketsCurrent` * Stocks * `stockCreate` * `stockUpdate` * `stockDelete` * Stock transfers * `stockTransferCreate` * `stockTransferUpdate` * `stockTransferUpdateAny` * `stockTransferDelete` * `stockTransferClose` * Stock transfer numberings * `stockTransferNumberingCreate` * `stockTransferNumberingUpdate` * `stockTransferNumberingDelete` * Stock takings * `stockTakingCreate` * `stockTakingUpdate` * `stockTakingDelete` * `stockTakingClose` * Tickets * `ticketCreate` * `ticketUpdate` * `ticketUpdateAny` * `ticketDelete` * `ticketRename` * `ticketSetDiscount` * `ticketSetCustomer` * `ticketClose` * `ticketCloseAny` * `ticketCloseAs` * `ticketCloseToAnyFiscal` * `ticketPrintPreliminary` * `ticketSplit` * `ticketMerge` * `ticketHandover` * `ticketTakeover` * `ticketRefund` * User * `userCreate` * `userUpdate` * `userDelete` * Vats * `vatCreate` * `vatUpdate` * `vatDelete` * Zones * `zoneCreate` * `zoneUpdate` * `zoneDelete` * Others * ~~`negativeSale`~~ (not enforced in current version) * `storno` * `admin` - represents the consolidation of all rights. When a user possesses this right, they are automatically granted all other rights. # Device environments Each device in system is created with specific environment, this enables to behave sessions related to given device in certain ways. List of system defined device environments:

Environment name	Description	Is sale environment
`BackOffice`	Used for PORTOS BackOffice application.	false
`CashRegister`	Used for PORTOS Cash register application (PORTOS Pokladňa)	true
`PDA`	Used for PORTOS Mobile cashier smartphone application (PORTOS Mobilný čašník)	true
`Tool`	Used for all other devices, such as PORTOS Link.	false

## Sale environment `CashRegister` and `PDA` environments are so called "*sale environments*". Sale environments are specific in several ways: * each "sale environment" device can hold up to one active session at the time. That means, if user is authenticated in cash register device and another request for authorization on same device is invoked, the earlier session is terminated by API. * some API actions (mainly related to ticket updating) are allowed only for users authenticated on sale environment devices. # Localization To receive localized error messages from API server, add `Accept-Language` header to each HTTP request. Following culture codes are supported:

Header value	Description	Is default
`en-GB`	English - United Kingdom	false
`sk-SK`	Slovak - Slovakia	true

If `Accept-Language` header is not speficied, or contains unsupported value, default language is used. # NData query syntax This section describes the query syntax used in PORTOS API, called "NData". ## What is NData? NData is custom syntax to perform server-side pagination, sorting, inclusion and filtering, inspired by [open stack syntax](https://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#pagination-filtering-and-sorting). ## Pagination Pagination allows to specify range of items received from the API. Pagination can be implemented using one or both of two query parameters: | Parameter | Name | Format | Description | | --------- | ---- | ------- | ------------------------------------------------------------------------- | | `$skip` | Skip | integer | Describing number of records to skip from beginning of result collection. | | `$take` | Take | integer | Maximum count of items to be returned. | ### Pagination examples | Uri query | Description | | --------------- | ------------------------------------ | | `$skip=10` | Skip first 10 items and return rest. | | `$take=5` |

Return at most 5 items |

| |

$skip=10&$take=5

$take=10&$skip=5

| Skip first 10 items and return _at most_ next 5 items. | ## Sorting Sorting allows to change order of returned items. | Parameter | Name | Format | Description | | --------- | ---- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `$sort` | Sort | comma separated list of sort keys. | More than one sort key may be specified. If multiple keys are specified, result collection is sorted by keys in order given by this parameter. | The caller may (but is not required to) specify a sort direction for each key. If a sort direction is not specified for a key, then a default is set by the server. Sort directions can optionally be appended to each sort key, separated by the `:` character. Supported sort directions are: | Sort direction | Name | Description | | -------------- | ------ | --------------------------------------------------------------------------------------------- | | Ascending | `asc` | This is an default sort direction. | | Descending | `desc` | Alternatively, descending sort direction can be specified as prepended minus (`-`) character. | ### Sorting examples | Uri query | Description | | -------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `$sort=value1,value2,value3` | Sort by value1, then by value2, then by value3. Directions are defaulted by server. | |

$sort=value1,value2:desc

| Sort by value 1, then sort by value2 descending. Sort direction for first value is defaulted by server. Please note the minus sign notation in second example. Both examples produces same result. | |

$sort=value1

and

$sort=value1,value1

| Multiple occurrence in query is supported, thus both queries are equal. | |

$sort=value1,value2:desc

and

$sort=value1,value2:DESC

| Sort descriptors are case insensitive. Both following queries are equal | ## Inclusion Inclusion allows to extend response format. | Parameter | Name | Format | Description | | ---------- | ------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | | `$include` | Include | comma separated list of keys. | Allows to specify one or more members (that are not part of output by default) to be included in response. | ### Inclusion examples | Uri query | Description | | ------------------------------------ | ----------------------------------------------------------- | | `$include=value` | Single key is specified to be included in API response. | | `$include=value1,value2,value3` | Multiple keys are specified to be included in API response. | ## Filtering API endpoint-specific filters are often supported, to filter result based on provided filter values. No global parameters are defined. Each endpoint-specific filter supports one or more parameters. Each parameter is identified by its name, below addressed as `FILTER_MEMBER`. ### Filtering syntax: operations, operator and operation arguments Value of each filter is semicolon-separated (`;`) list of *operations*. > Syntax: `FILTER_MEMBER=OPERATION1;OPERATION2` Each operation consists of *segments* delimited by colon (`:`) character. First segment is an *operator*, followed by 0 or more *operation arguments*. > Syntax: `FILTER_MEMBER=OPERATOR:OPERATION_ARGUMENT1:OPERATION_ARGUMENT2` > Example: Filter member named "DiscountRate" is associated with single operation, that has "gt" operator and one operation argument, value 10. Result query is: `DiscountRate=gt:10` ### Multiple filter occurrence Multiple occurrence of same filter member is supported, thus both following queries are equal: * `DiscountRate=gt:0&DiscountRate=lt:50` * `DiscountRate=gt:0;lt:50` ### Operators Each filter may support one or more operators. Usually, well-known operators (listed below) are used. Each filter may, however, support *custom operators* - operators with custom name. #### Well-known operators | Operator | Name | Description | | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------- | | `eq` | Equal |

This is default operator, if not stated otherwise. Operation with this operator expects single operation argument.

| | `neq` | Not equal |

Specifies that filter member value must not be equal to provided operation argument. Operation with this operator expects single operation argument.

| | `in` | In | Specifies that filter member value must be equal to one of values provided in operation argument. Operation with this operator expects single _operation argument_ - the collection with one or more elements. | | `nin` | Not in | Specifies that filter member value must not be equal to any value provided in operation argument. Operation with this operator expects single _operation argument_ - the collection with one or more elements. | | `gt` | Greater than | Specifies that filter member value must be greater than value provided in operation argument. Operation with this operator expects single _operation argument_. | | `gte` | Greater than or equal to | Specifies that filter member value must be greater than or equal to value provided in operation argument. Operation with this operator expects single _operation argument_. | | `lt` | Less than | Specifies that filter member value must be less than value provided in operation argument. Operation with this operator expects single _operation argument_. | | `lte` | Less than or equal to | Specifies that filter member value must be less than or equal to value provided in operation argument. Operation with this operator expects single argument. | #### Custom operator The filter may support custom operator - an operator with custom name (and behavior). > Example: If filter named "Foo" supports the custom operator named "op", accepting "bar" as an operation argument, example query would look like this: `Foo=op:bar`. #### Default operator The filter syntax allows not to specify the operator explicitly. If no operator is explicitly specified in the URI, default operator is used. Each filter may have different default operator. If not stated otherwise, the default operator is `eq`. > Example: With assumption that `eq` operator is default operator for "DiscountRate" filter, both following queries are equal: > > * `DiscountRate=eq:10` > * `DiscountRate=10` > Example: If filter named "Foo" has the custom operation "op" marked as default, you can specify the query from example above without explicitly stating the operator, like this: `Foo=bar`. ### Collection operation arguments Some operators, such as `in` and `nin` are paired with argument that is an collection. To delimit these values within operation argument, comma character (`,`) is used. Example: Filter named `Month` with one operation, that has `in` operator and one argument that is an collection of three string values: "`January`", "`February`" and "`March`". ``` Month=in:January,February,March ``` ### Operation argument escaping Operation argument must be encapsulated in double quotation marks (`"`) if their string representation contains at least one of following special characters: * `,` (conflict with collection operation argument separator) * `:` (conflict with operation segments separator) * `;` (conflict with operations separator) ``` FilterMember=eq:"argument:with,special;characters" ``` If argument is an collection, each value is escaped separately: ``` FilterMember=in:"foo:bar","foo,bar","foo;bar" ``` If argument contains double quotation mark character `"`, this character must be escaped with backslash `\`. Example: Filter named "Actor" associated with operation with `eq` operator and string value `Dwayne "The Rock" Johnson`: ``` Actor=eq:"Dwayne \"The Rock\" Johnson" ``` {% hint style="success" %} URI Encoding: If NData query is transfered in URI, URI encoding takes place after all NData syntactic rules being applied. Valid URI value would be: ``` Actor=eq:%22Dwayne%2520%255C%2522The%2520Rock%255C%2522%2520Johnson%22 ``` {% endhint %} # OpenAPI specification To open HTML page with all listed API methods, you can open following address in your internet browser: `{{server_address}}/docs`. To download the API blueprint in Swagger format, simply click on the "Download" button located next to the "*Download OpenAPI specification*" label. The resulting JSON file can be utilized in an API client generator or visualized on [swagger.io](https://editor.swagger.io/). # Data models This page contains data models that are utilized across multiple resources. The property type convention in this context follows the notation of C# (.NET). The presence of a quotation mark (`?`) indicates the nullability of a value. For example, a `string` property cannot be null, whereas a property of type `string?` can have a null value. ## Additive Enumeration with the following values: | Value | English Term | Slovak Term | | ----------------------- | ------------------------------ | ------------------------------ | | `colorant` | Colorants | Farbivá | | `colorantAdverseEffect` | Colorants with adverse effects | Farbivá s nežiaducimi účinkami | | `preservatives` | Preservatives | Konzervanty | | `antioxidant` | Antioxidants | Antioxidanty | | `flavorEnhancer` | Flavor enhancers | Zvýrazňovače chuti | | `sulfites` | Sulfites | Siričitany | | `blackened` | Blackened/carbon coloring | Uhlíkové zafarbenie (černenie) | | `waxed` | Waxed | Voskované | | `phosphate` | Phosphate | Fosfát | | `sweetener` | Sweeteners | Sladidlá | | `caffeine` | Caffeine | Kofeín | | `quinine` | Quinine | Chinín | | `geneticallymodified` | Genetically modified | Geneticky modifikované | | `acidifiers` | Acidifiers | Okysľovadlá | | `stabilisers` | Stabilisers | Stabilizátory | | `protein` | Protein | Bielkoviny | ## Allergen Enumeration with the following values: | Value | English Term | Slovak Term | | ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `celery` | Celery | Zeler a výrobky z neho | | `cereal` | Cereal grains | Obilniny obsahujúce lepok (pšenica, raž, jačmeň, ovos, špalda, kamut alebo ich hybridné odrody) | | `crustaceans` | Crustaceans | Kôrovce a výrobky z nich (napr. krevety, kraby) | | `eggs` | Eggs | Vajcia a výrobky z nich | | `fish` | Fish | Ryby a výrobky z nich | | `lupin` | Lupin | Vlčí bôb (lupina) a výrobky z neho | | `milk` | Milk | Mlieko a výrobky z neho (vrátane laktózy) | | `molluscs` | Molluscs | Mäkkýše a výrobky z nich (napr. mušle, slávky) | | `mustard` | Mustard | Horčica a výrobky z nej | | `peanuts` | Peanuts | Arašidy a výrobky z nich | | `sesameSeeds` | Sesame seeds | Sezamové semená a výrobky z nich | | `soybeans` | Soybeans | Sójové zrná a výrobky z nich | | `sulphurDioxideSulphites` | Sulphur dioxide/sulphites | Oxid siričitý a siričitany (v koncentráciách vyšších ako 10 mg/kg alebo 10 mg/l) | | `nuts` | Nuts | Orechy (mandle, lieskové orechy, vlašské orechy, kešu, pekanové orechy, para orechy, pistácie, makadamové orechy alebo queenslandské orechy) | ## Address

Property name	Type	Description
`street`	`string?`	Street name, office number and/or building number.
`city`	`string?`	City
`zipCode`	`string?`	Postal code
`country`	`string?`	Country

## ApiKey

Property name	Type	Description
`id`	`string`	Unique identifier.
`clientId`	`string`	Public API key.
`clientSecret`	`string`	API secret key, used to hash request payload.
`isActive`	`bool`	Indicates whether given API key can be used.
`createdAt`	`DateTime`	Date and time, when the API key was created.
`name`	`string`	Something users will recognize and trust.
`description`	`string?`	This is displayed to all potential users of your application.
`userName`	`string`	User identifier associated with given API key.
`deviceName`	`string`	Device name associated with given API key.
`permissions`	`string[]`	Collection of permissions associated with given API key.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## ArticleCategory Each product or service within the PORTOS system is linked to a specific category, which is referred to as the article category. This categorization helps in organizing and classifying items, allowing for efficient management and navigation within the system.

Property name	Type	Description
`label`	`string`	Unique abbreviation of article category description, which may contain up to 3 characters.
`description`	`string`	Full name (descripition) of article category, visible for cashiers.
`customerDescription`	`string?`	Full description for customer (used mostly in menus)
`courseNumber`	`int?`	Optional course number that will be initially applied to product associated with given article category.
`color`	`string?`	Color in RGB format, including leading `#` symbol. E.g. `#fff` or `#aabbcc`.
`sortHint`	`int?`	Optional sort hint (to order article categories in cash register application)
`tags`	`string[]?`	Optional collection of tags (used in statistics).
`ordering`	`ArticleCategoryOrderingItem[]`	Ordering settings for article category.
`_v`	`int`	Resource version. This property is tracked and updated by API.

`SortHint` property is used to achieve user defined article categories sorting in cash register application(s). This optional property is of nullable integer type. Article categories with lowest value are displayed first, `null` have lowest priority. Categories with same `SortHint` value are sorted alphabetically. Example:

SortHint	Description
0	Beers
0	Drinks
1	Pizza
2	Wine
null	Beverages
null	Specials

## ArticleCategoryOrderingItem Settings for article category ([`ArticleCategory`](#articlecategory)) ordering related to specific [`OrderOrigin`](#orderorigin).

Property name	Type	Description
`orderOrigin`	`OrderOrigin`	Order origin associated with this item.
`enabled`	`bool`	Determines whether given type of order origin is enabled for associated Article category.
`weeklySchedule`	`WeeklyScheduleItem[]`	Gets ordering weekly schedule. If value is `null` or empty collection, schedule is not limited and article category is available 24/7. Otherwise, schedule is specified by items in collection. Empty collection means no time slots restrictions.

## PluPackaging ## AuthResult

Name	Type	Description
`tokenId`	`string`	The JWT token using for authenticating requests.
`refreshToken`	`string`	The refresh token.
`user`	`UserProfileContext`	The user profile consists of information about the user themselves and the settings of the device they are logged onto. Depending on the device type, the structure of `settings` and `preferences` may vary.

## BackOfficeDeviceSettings No properties are currently defined. Settings are managed directly in PORTOS BackOffice application. ## BankAccount

Property name	Type	Description
`bankCountry`	`string?`	The country where the bank associated with the account is located. It represents the jurisdiction and regulatory framework under which the bank operates.
`bankName`	`string?`	The name of the bank where the account is held.
`iban`	`string?`	International Bank Account Number. A standardized numerical code used to identify a specific bank account internationally.
`number`	`string?`	Bank account number in older (non international) format.
`swift`	`string?`	SWIFT code (also known as BIC - Bank Identifier Code) is a unique identification code assigned to each bank globally.

## CashRegisterDeviceSettings

Name	Type	Description
`MaxQuantity`	`decimal?`	Maximal quantity user can specify in single ticket item.
`DefaultFiscalName`	`string?`	Determines name of fiscal device associated with cash register. Usage of different fiscal device may be conditioned by rights of authorized user.
`OpenedPrices`	`bool`	Determines whether user can specify unit price of ticket item different than product's unit price.
`NoticeOnNegativeSale`	`bool`	Determines whether insufficient PLU stock quantity would be indicated to authorized user.
`VisibleQuantities`	`bool`	Determines whether PLU stock quantities can be visible for authorized user. Otherwise, application must not display such information.
`DefaultOrderEndpointName`	`string?`	Determines name of order endpoint device associated with cash register. Usage of different order endpoint may be conditioned by rights of authorized user.
`DefaultStockName`	`string?`	Determines name of stock associated with cash register. Usage of different stock may be conditioned by rights of authorized user.

All other settings are managed directly in the PORTOS Cash register application (PORTOS Pokladňa). ## CashTransfer

Property name	Type	Description
`amount`	`Price`	Cash transfer operation amount. Positive for deposit or negative for withdrawal.
`date`	`DateTime`	Date and time of cash transfer operation
`employee`	`UserInfo`	Employee who performed cash transfer operation.

## Company

Name	Type	Description
`id`	`string`	Unique company identifier. If not specified, ID is generated by API.
`isActive`	`bool`	Gets whether this company is active and can be used (e.g. paired with stock transfers).
`name`	`string`	Company name.
`crn`	`string`	Company registration number (known as IČO, in Slovak Republic)
`vatId`	`string`	VAT ID (known as IČ DPH, in Slovak Republic)
`taxId`	`string`	TAX ID (known as DIČ, in Slovak Republic)
`isTaxPayer`	`bool`	Gets whether this company is tax payer.
`register`	`string?`	The company's entry in the business register
`dueDays`	`int?`	The number of days given to a company for payment after issuing an invoice.
`type`	`CompanyType`	The company categorization.
`discountRate`	`decimal`	Discount rate percentage, with value between 0 and 100, with precision up to two decimal places, that is automatically assigned to invoice associated with given company.
`isDefault`	`bool`	When `true`, this record represents merchant (owner of cash register system).
`addresses`	`CompanyAddress[]`	The addresses associated with company.
`bankAccounts`	`CompanyBankAccount[]`	The bank accounts associated with company.
`contacts`	`CompanyContact[]`	The contacts associated with company.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## CompanyType Enumeration with the following values:

Value	Description
`unknown`	Type used when company is not exclusively supplier nor purchaser.
`supplier`	Company that is responsible for producing or delivering the products.
`purchaser`	Also known as a buyer, is a company acquires goods or services from a merchant.

## CompanyAddress

Property name	Type	Description
`street`	`string?`	Street name, office number and/or building number.
`city`	`string?`	City
`zipCode`	`string?`	Postal code
`country`	`string?`	Country
`type`	`CompanyAddressType`	Specifies purpose of address.

## CompanyAddressType Enumeration with the following values:

Value	Description
`unknown`	The specific purpose or nature of the address is not known or specified. It might be used when the address information is incomplete or when there is a lack of information about the purpose of the address.
`office`	An office address refers to the physical location where a company or organization conducts its business operations.
`billing`	The address to which invoices, bills, or payment requests are sent.
`shipping`	Tthe destination address where goods or products are to be delivered.
`other`	Any address that does not fit into the predefined types mentioned above.

## CompanyBankAccount

Property name	Type	Description
`bankCountry`	`string?`	The country where the bank associated with the account is located. It represents the jurisdiction and regulatory framework under which the bank operates.
`bankName`	`string?`	The name of the bank where the account is held.
`iban`	`string?`	International Bank Account Number. A standardized numerical code used to identify a specific bank account internationally.
`number`	`string?`	Bank account number in older (non international) format.
`swift`	`string?`	SWIFT code (also known as BIC - Bank Identifier Code) is a unique identification code assigned to each bank globally.
`isDefault`	`bool`	Indicates whether the bank account is set as the primary account for company.

## Contact

Property name	Type	Description
`fax`	`string?`	Fax number associated with a person.
`phone`	`string?`	Telephone number associated with a person's landline or fixed-line phone.
`mobile`	`string?`	Telephone number associated with a person's mobile device.
`email`	`string?`	Person's email address.

## CompanyContact

Property name	Type	Description
`name`	`string?`	Given or first name of an individual.
`surname`	`string?`	The inherited or family name of an individual.
`email`	`string?`	Person's email address.
`mobile`	`string?`	Telephone number associated with a person's mobile device.
`phone`	`string?`	Telephone number associated with a person's landline or fixed-line phone.
`fax`	`string?`	Fax number associated with a person.
`isDefault`	`string?`	Indicates whether a particular contact is primary contact for associated company.
`note`	`string?`	Helds any relevant additional information or comments about the contact. It can be used to include any specific details or instructions related to the contact or communication with the person.

## CountQueryResult This model is returned for all GET collection routes when `$count` query parameter is set to `true`. Opposing to [`QueryResult`](#queryresult), This model is used to retrieve only count of elements, not elements themself.

Property name	Type	Description
`count`	`int`	Number of elements matching the query.
`totalCount`	`int`	Number of total resources available. Value may differ from `count`, when pagination or filtering is applied.

## Currency

Property name	Type	Description
`label`	`string`	The three-letter currency code ISO4217 standard.
`sign`	`string?`	Visual representation used to denote a specific currency in written or printed form. For example, the symbol for the United States Dollar is $, while the Euro is represented by €.
`isDomestic`	`bool`	Indicates whether a currency is considered the domestic currency of a particular country or region.
`exchangeRate`	`decimal`	Represents the rate at which one currency can be exchanged for another. Domestic currency's exchange rate is equal to 1.
`description`	`string`	Currency's full name.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## Customer

Name	Type	Description
`id`	`string`	Unique customer identifier. If not specified, ID is generated by API.
`externalId`	`string?`	Unique identifier provided by external system.
`isActive`	`bool`	Gets whether this customer is active and can be used (e.g. paired with tickets).
`status`	`string`	Customer state. One of following: `valid`, `notYetValid`, `expired`.
`activationTime`	`DateTime?`	Date and time since customer is active.
`expirationTime`	`DateTime?`	Date and time until customer is acive.
`firstName`	`string?`	First name.
`lastName`	`string?`	Second name.
`fullName`	`string?`	Full or display name (if not provided, combination of `firstName` and `lastName` is used.
`gender`	`string?`	`male`, `female` or `null` for other/unspecified.
`birthDate`	`DateTime?`	Birth date.
`email`	`string?`	Customer email.
`phone`	`string?`	Phone number.
`isCompany`	`bool`	Specifies wheter customer is associated with company.
`company`	`CustomerCompany?`	Information about company associated with customer.
`address`	`CustomerAddress?`	Customer address.
`deliveryAddress`	`CustomerAddress?`	Customer delivery address.
`credit`	`Price`	Cash balance on customer account.
`creditTransaction`	`CustomerCreditTransaction[]`	History of financial operations that affects `credit`.
`cards`	`CustomerCard[]`	Collection of cards associated with customer.
`creditRate`	`decimal`	Cashback coeficient. If set to `0.01`, for every spent unit of currency, one cent is returned as cash back to credit balance. Must be positive number or zero.
`discountRate`	`decimal`	Discount rate with value between 0 and 100. Up to 2 decimal places.
`note`	`string?`	Optional note.
meta	`Meta`	Object that holds additional data (usually supplied by external system).
`_v`	`int`	Resource version. This property is tracked and updated by API.

## CustomerAddress

Name	Type	Description
`street`	`string`	Street name and building number
`city`	`string`	City
`postalCode`	`string?`	Postal code
`country`	`string`	Country
`coordinates`	`GeoCoordinates?`	GPS coordinates
`note`	`string?`	Note related to customer address

## CustomerCard

Name	Type	Description
`externalId`	`string?`
`isActive`	`bool`	Specifies whether this card is active and can be used.
`isVirtual`	`bool`	Specifies whether this card has physical representation.
`serialNumber`	`string`	Unique serial number. This value is unique across all customers stored in system.
`processor`	`string`	`P` for physical cards, `G` as general for other card types.
`status`	`CustomerCardStatus`	Card status.
`statusTime`	`DateTime?`	Date and time of last status change.
`statusReason`	`string?`	Status change reason.
`activationTime`	`DateTime`	The date and time from which the card will be valid.
`expirationTime`	`DateTime?`	The date and time until which the card will be valid.
`note`	`string?`	Optional note related to this customer card.
`meta`	`Meta`	Object that holds additional data (usually supplied by external system).
`_v`	`int`	Resource version. This property is tracked and updated by API.

## CustomerCardStatus Enumeration with the following values: * `NotIssued`: the card is created in system, but not issued yet. * `IssueFailed`: card issuing failed. * `IssueCanceled`: card issuing has been canceled. * `IssueSkipped`: card issuing has been skipped, as one or more conditions were not met. * `ReissueRequested`: a reissue was requested. * `Valid`: card is issued and valid (active already and not yet expired) * `NotYetValid`: Card is issued but not yet valid (`activationTime` has not been reached yet). * `Expired`: card is expired (`expirationTime` has been reached). * `Blocked`: card is blocked (e.g. has been lost or compromised) * `DisposeRequested`: card disposal has been requested. * `Disposed`: card has been disposed. ## CustomerCompany

Name	Type	Description
`name`	`string?`	Company name.
`crn`	`string?`	Company registration number (IČO).
`vatId`	`string?`	Company VAT identifier (IČ DPH)
`taxId`	`string?`	Company TAX identifier (DIČ)

## CustomerCreditTransaction

Name	Type	Description
`id`	`string`	Unique transaction identifier.
`externalId`	`string?`	External identifier supplied by client-side or external system.
`sequenceNumber`	`int`	Transactions sequence number. Value is supplied by API.
`amount`	`Price`	Transaction amount. Can be positive or negative number.
`type`	`CustomerCreditTransactionType`	Type of transaction.
`endingCreditBalanceAmount`	`Price`	Resulting credit balance after transaction.
`creationTime`	`DateTime`	Date and time of transaction.
`note`	`string?`	Optional note related to transaction.
`meta`	`Meta`	Object that holds additional data (usually supplied by external system).

## CustomerCreditTransactionType Enumeration with the following values: * `adjustment`: credit consumption or cash-back * `deposit`: credit top up * `withdrawal`: funds withdrawal * `correction`: manual balance correction * `other`: none of above ## DailySalesReport

Name	Type	Description
`id`	`string`	Unique identifier. If not specified, ID is generated by API.
`fiscalName`	`bool`	Name of fiscal device associated with given daily sales report.
`number`	`bool`	Daily sales report sequence number, unique within specific `fiscalName` an `fiscalMemorySerialNumber`.
`fiscalMemorySerialNumber`	`string`	Serial number of fiscal memory inserted in fiscal device.
`openDate`	`DateTime`	Date and time of daily sales report creation (related to first ticket closure or first cash transfer since previous daily sales report).
`closeDate`	`DateTime?`	Date and time of daily sales report closure.
`currencyLabel`	`string`	Label of currency, in which all money information is stored for this daily sales report
`cashTransfers`	`CashTransfer[]`	Collection of cash transfers.
`fiscalInfo`	`DailySalesReportFiscalInfo?`	Information determined during fiscal daily sales report closing procedure. Is null when `state` is `open` or `manuallyClosed`. Is not null, when `state` is `closed`.
`state`	`DailySalesReportStatus`
`_v`	`int`	Resource version. This property is tracked and updated by API.

## DailySalesReportCopyContext This model is used to specify the daily sales report for which a copy is going to be printed. The daily sales report can be identified by either its number (`dailySalesReportNumber` property) or the closing date of the report (`dailySalesReportDate` properties).

Name	Type	Description
`dailySalesReportNumber`	`int?`	Daily sales report number.
`dailySalesReportDate`	`DateTime?`	Daily sales report close date.

## DailySalesReportFiscalInfo

Property name	Type	Description
`ticketsCount`	`int`	Number of tickets with `cashRegister` type associated with given daily sales report.
`ticketsAmountIncludingVat`	`Price`	Total amount (including VAT) of all associated tickets with `cashRegister` type.
`invalidTicketsCount`	`int`	Number of tickets with `invalid` type associated with given daily sales report.
`invalidTicketsAmountIncludingVat`	`Price`	Total amount (including VAT) of all associated tickets with `invalid` type.
`invoiceTicketsCount`	`int`	Number of tickets with `invoice` type associated with given daily sales report.
`invoiceTicketsAmountIncludingVat`	`Price`	Total amount (including VAT) of all associated tickets with `invoice` type.
`positiveTicketItemsCount`	`int`	Number of ticket items with `positive` type in associated tickets.
`positiveTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `positive` type in associated tickets.
`tipTicketItemsCount`	`int`	Number of ticket items with `tip` type in associated tickets.
`tipTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `tip` type in associated tickets.
`returnedContainerTicketItemsCount`	`int`	Number of ticket items with `returnedContainer` type in associated tickets.
`returnedContainerTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `returnedContainer` type in associated tickets.
`returnedTicketItemsCount`	`int`	Number of ticket items with `returned` type in associated tickets.
`returnedTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `returned` type in associated tickets.
`correctionTicketItemsCount`	`int`	Number of ticket items with `correction` type in associated tickets.
`correctionTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `correction` type in associated tickets.
`discountTicketItemsCount`	`int`	Number of ticket items with `discount` type in associated tickets.
`discountTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `discount` type in associated tickets.
`advanceTicketItemsCount`	`int`	Number of ticket items with `advance` type in associated tickets.
`advanceTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `advance` type in associated tickets.
`creditTicketItemsCount`	`int`	Number of ticket items with `credit` type in associated tickets.
`creditTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `credit` type in associated tickets.
`voucherTicketItemsCount`	`int`	Number of ticket items with `voucher` in associated tickets.
`voucherTicketItemsAmountIncludingVat`	`Price`	Total amount of ticket items with `voucher` type in associated tickets.
`vatIncomes`	`VatIncome[]`	Total turnovers grouped by VAT category and rate.
grandTotalAmountIncludingVat	`Price`	Cumulative total turnover across all daily sales reports for given fiscal device and fical memory serial number.
roundingDown	`Price`	Sum of roundings towards zero.
roundingUp	`Price`	Sum of roundings away from zero.

## DailySalesReportStatus Enumeration with the following values:

Value	Description
`open`	Daily sales report is opened. Additional tickets and cash transfers can be associated with given daily sales report.
`manuallyClosed`	Associated daily sales report is marked as closed (value of `fiscalInfo` property may remain `null`)
`closed`	Daily sales report is closed. `fiscalInfo` property contains summary information containing all realated tickets and cash transfers.

## DayOfWeek Specifies the day of the week. Enumeration with the following values:

Value	Description
`Sunday`	Indicates Sunday.
`Monday`	Indicates Monday.
`Tuesday`	Indicates Tuesday.
`Wednesday`	Indicates Wednesday.
`Thursday`	Indicates Thursday.
`Friday`	Indicates Friday.
`Saturday`	Indicates Saturday.

## Device

Property name	Type	Description
`name`	`string`	Unique device name.
`isActive`	`bool`	Indicates whether a device is active and can be associated with user session.
`envName`	`string`	Name of the device environment.
`description`	`string`	Human readable device description (e.g. "Cash register 1").
`roles`	`string[]`	Collection of user rights that are initially associated to user, when user is given access to this device. Roles collection can be adjusted for every user.
`preferences`	`object`	Object containing user-specific preferences for this device. Reserved for future use.
`settings`	`BackOfficeDeviceSettings` \| `CashRegisterDeviceSettings` \| `PDADeviceSettings` \| `ToolDeviceSettings`	An object with string properties, that is used to store device settings. The value of each property within the object corresponds to a specific type based on the `envName` (device environment name).
`_v`	`int`	Resource version. This property is tracked and updated by API.

## EmailTicketFormOptions

Name	Type	Description
`To`	`string`	The e-mail address of the recipient (customer) to whom the e-receipt is sent.
`FooterText`	`string`	The optional text that is displayed on end of receipt. Only non-control characters are allowed (and CR + LF).

## EnergyUnit Represents the unit of energy measurement. | Name | Description | | ------ | ------------- | | `Kcal` | Kilocalories. | | `Kj` | Kilojoules. | ## EnergyValue | Property Name | Type | Description | | ------------- | --------------------------- | ----------------------------------- | | `Amount` | `decimal` | The amount of energy. | | `Unit` | [`EnergyUnit`](#energyunit) | The unit of the energy measurement. | ## Fiscal

Property name	Type	Description
`name`	`string`	Unique fiscal device name.
`isActive`	`bool`	Indicates whether given fiscal device can be used in ticket closing procedure.
`type`	`string`	Type of hardware device.
`version`	`string?`	Reserved for future use.
`dkp`	`string`	Unique cash register code (also known as DKP in Slovak republic).
`settings`	`object`	Settings related to given fiscal device. Object may vary based on `type` property.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## ForeignPrice Similiar to [`Price`](#price), however this model can hold information about non-domestic currency.

Property name	Type	Description
`amount`	`decimal`	Up to 2 decimal places.
`currencyLabel`	`string`	3-characters long foreign currency label (ISO 4217).
`domesticCurrencyLabel`	`string`	3-characters long domestic currency label (ISO 4217).
`exchangeRate`	`decimal`	Conversion rate between foreign and domestic currency. When currency is equal to domestic currency, exchange rate is equal to 1.

## GeoCoordinates Represents GPS coordinates.

Property name	Type	Description
`longitude`	`decimal`	Value in range of -180 to 180.
`latitude`	`decimal`	Value in range of -90 to 90.

## IntervalSalesReportContext This model is used to specify the interval of daily sales reports, for which a interval sales report is going to be printed. The interval can be defined either by specifying a range of daily sales report numbers (`dsrNumberFrom` and `dsrNumberTo` properties) or by indicating the closing dates of the daily sales reports (`dsrDateFrom` and `dsrDateTo` properties).

Name	Type	Description
`dsrDateFrom`	`DateTime?`	Close date of first daily sales report in selected interval.
`dsrDateTo`	`DateTime?`	Close date of last daily sales report in selected interval.
`dsrNumberFrom`	`int?`	Number of first daily sales report in selected interval.
`dsrNumberTo`	`int?`	Number of last daily sales report in selected interval.

## License

Name	Type	Description
`shopId`	`int`	Unique identifier of venue, issued by PORTOS reseller.
`activationTime`	`DateTime`	Activation date and time.
`expirationTime`	`DateTime`	Expiration date and time.
`verificationTime`	`DateTime?`	Date and time of last verification.
`verificationInterval`	`TimeSpan`	Verification interval.
`features`	`LicenseFeature[]`	Collection of features associated with license.
`remainingDays`	`int`	Number of remaining days before license expiration.
`isExpired`	`bool`	Indicates whether license is expired.

## LicenseFeature

Name	Type	Description
`productSku`	`string`	The feature identifier.
`rawValue`	`string?`	Value associated with feature.
`name`	`string`	Feature display name.
`activationTime`	`DateTime`	Activation date and time.
`expirationTime`	`DateTime?`	Expiration date and time.

## MeasureQuantity Unlike the [`Quantity`](#quantity) type, this model has a known [unit of measure](#measureunit).

Property name	Type	Description
`amount`	`decimal`	Quantity amount.
`unit`	`MeasureUnit`	Measurement unit.

## MeasureUnit Enumeration with the following values:

Value	Description	Dimension
`mg`	Milligram	Weight (Mass)
`g`	Gram	Weight (Mass)
`dag`	Decagram	Weight (Mass)
`kg`	Kilogram	Weight (Mass)
`ml`	Milliliter	Volume
`dl`	Deciliter	Volume
`l`	Liter	Volume
`mm`	Millimeter	Length
`cm`	Centimeter	Length
`dm`	Decimeter	Length
`m`	Meter	Length

## Meta Meta is an object with dynamic properties of string type. Can be parsed to `Dictionary` instance. Is used to hold additional data, usually supplied by external system. ## Modifier

Name	Type	Description
`id`	`string`	Unique identifier
`name`	`string`	Name of modifier. Eg. "Steak doneness"
`displayName`	`string?`	Name to be displayed for customer. Eg. "Pick steak doneness". If not provided, `name` is displayed in digital menu.
`minimumSelectedOptionsCount`	`int`	Minimum count of selected unique options. This value is greater than zero if modifier is required.
`maximumSelectedOptionsCount`	`int?`	Maximum count of selected unique options. If set to `null`, then options count is unlimited.
`maximumSelectedOptionsTotalQuantity`	`int`	The maximum number of all selected options in total that the customer can choose.
`options`	`ModifierOption[]`	Options collection.

## ModifierOption

Name	Type	Description
`id`	`string`	Option identifier, unique within associated modifier options collection.
`name`	`string`	Modifier option name, e.g. "medium rare".
`unitPrice`	`UnitPrice?`	Optional unit price. If not specified, price of referenced product is used. Otherwise, modifier does not modify the price of associated ticket item.
`isUnitPriceIncludingVat`	`bool`	Specifies whether `unitPrice` includes VAT.
`pluId`	`PluId?`	Optional PLU reference.
`defaultSelectedQuantity`	`int`	Default selected quantity.
`maximumSelectedQuantity`	`int?`	Maximum number of selections for this option. If set to `null`, then quantity is not limited.

## NonfiscalRecordContentFlags Enumeration with the following values:

Value	Description
`none`	The document does not contain any data that would require special processing.
`priceInformation`	The document contains information about the price of goods or the price of a service. Added in version `4.3`.

If this flag is set, in some implementations of the printing service the text “NEPLATNÝ DOKLAD” will be printed on every third line of the document in order to comply with [§5(3)(t) of the Act on the Registration of Sales](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-t). ## NonfiscalRecordContext

Name	Type	Description
`recordBody`	`string`	Body of nonfiscal record.
`contentFlags`	`NonfiscalRecordContentFlags[]?`	Specifies additional characteristics of the content. Indicates whether the record contains data that requires special processing (for example, price information that may trigger regulatory printing rules). If value is not provided, fallback value (`[ "priceInformation" ]` is used.

## NumberingPeriodUnit Enumeration with the following values:

Value	Description
`day`	Day
`month`	Month
`year`	year

## Order

Name	Type	Description
`id`	`string`	Unique identifier
`number`	`int`	Sequence number generated by API. This number may serve as pickup code for customer.
`deviceName`	`string`	Name of device, from which the order processing request has been invoked.
`user`	`UserInfo`	User that invoked order processing request.
`ticket`	`OrderTicketInfo`	Information about ticket that is associated with given order.
`items`	`OrderItem[]`	Order items collection.

## OrderEndpoint

Name	Type	Description
`name`	`string`	Unique name.
`isActive`	`bool`	Indicates whether order endpoint is used to accept orders.
`address`	`string?`	Order endpoint address (e.g. location of network printer).
`type`	`string`	Type of order endpoint (e.g. printer manufacturer and/or printer model, or kitchen tablet application/driver name).
`settings`	`object`	Based on `type`, properties of settings object may vary.

## OrderItem

Name	Type	Description
`id`	`int?`	Unique item identifier within order.
`plu`	`OrderItemPlu`	Information related to product.
`quantity`	`Quantity`	Ordered product quantity.
`comment`	`string?`	Optional comment/note from cashier.
`courseNumber`	`int?`	This optional property serves as an indicator for the sequential delivery of food to the table. It allows for the organization and coordination of food service by assigning a specific order or sequence to each dish. This number provides valuable information to ensure that dishes are delivered to the table in the desired order, optimizing the dining experience for the customers.
`endpoints`	`OrderItemEndpoint[]`	Contains collection of state changes related to each oder endpoint this order is being processed on.

## OrderItemEndpoint

Name	Type	Description
`name`	`string`	Name of associated order endpoint device.
`statusChanges`	`OrderItemEndpointStatusChange[]`	History of order state changes related to associated order endpoint.
`orderItemStatus`	`OrderStatus`	Current status of order related to associated order endpoint.
`isProcessed`	`bool`	Indicates whether the order is already processed on given order endpoint.
`isProcessable`	`bool`	Indiates whether the order is processable on given order endpoint (is not in terminal state).

## OrderItemEndpointStatusChange

Name	Type	Description
`status`	`OrderStatus`	Status of order at the time of change.
`date`	`DateTime`	Date and time of status change.

## OrderItemPlu

Name	Type	Description
`name`	`string`	Name of product (PLU).
`code`	`int`	Product code (unique within given stock)
`stockName`	`string`	Name of the stock to which the product is associated

## OrderOrigin Describes the origin of the order.

Value	Description
`cashier`	Order is taken in store by cashier (personnel)
`online`	Order is placed online by customer (e.g. e-shop, delivery platform, etc.)

## OrderTicketInfo

Name	Type	Description
`id`	`string`	Ticket identifier.
`name`	`string`	Ticket name.
`location`	`TicketLocation?`	Ticket location.
`purchaseType`	`PurchaseType`	Ticket purchase type.
`customer`	`TicketCustomerInfo?`	Information about customer associated with ticket.
`version`	`int`	Version of ticket at time of order creation.

## OrderStatus These are the various states that an [order](#order) can go through during its processing and fulfillment. Each state provides valuable insights into the current status of the [order](#order), ensuring transparency and effective communication throughout the process. Please find below the detailed descriptions for each order state:

Value	Description
`unknown`	The default state. It indicates that the order processing status is currently unknown and/or has not been initiated.
`created`	The initial state when the order is created, but no further processing has taken place. At this stage, the order is in the system, awaiting further actions.
`sent`	The order has been successfully sent to the designated order endpoint for processing.
`delivered`	The order has been successfully delivered to the designated order endpoint. However, at this point, the endpoint may either accept or refuse the order.
`refused`	The order was refused by the order endpoint, indicating that the order endpoint has declined to accept and process the order. This refusal could be caused by various reasons, such as a shortage of food supplies or a failure of the coffee machine, so it is unable to fulfill the order at that specific moment.
`failed`	There was an attempt to send or deliver the order to the order endpoint, but it could not be completed due to an error. This could be due to technical issues or other factors preventing successful delivery.
`accepted`	The order was successfully delivered to the order endpoint, displayed, and accepted by the recipient (e.g., a chef received the order and acknowledged it). This state indicates that the recipient is ready to proceed with the fulfillment of the order.
`processSkipped`	The processing of the order was intentionally skipped. This could occur when the order endpoint device was marked as inactive during the processing attempt.
`processed`	The order has been marked as completed by the order endpoint, signifying the successful execution of all necessary processing steps, and confirming that the order is now fulfilled and the goods are ready for pickup.

Please see the state transition diagram below. The arrows between the states indicate the allowed transitions that the order can take. {% @mermaid/diagram content="stateDiagram-v2 \[\*] --> Unknown Unknown --> Created Unknown --> Failed Created --> Sent Created --> Failed Created --> ProcessSkipped Created --> Processed Sent --> Delivered Sent --> Refused Delivered --> Accepted Delivered --> Refused Delivered --> Failed Delivered --> Processed Failed --> Failed Failed --> Processed Failed --> ProcessSkipped Accepted --> Failed Accepted --> Processed Processed --> \[*] ProcessSkipped --> \[*] Refused --> \[\*] " %} Order is **processable** if state is `created` or `failed`. The order reaches its **final state** when it is either `refused,` `processed` or `processSkipped` and no further state transitions are permitted beyond this point. ## OrderStatusContext

Name	Type	Description
`status`	`OrderStatus`	Desired order status. Please note that only specific order staus transitions are allowed. See `OrderStatus` for more information.

## PaymentType

Property name	Type	Description
`number`	`int`	Unique payment type number. Value must be in range from 1 to 10.
`category`	`PaymentTypeCategory`	Category of payment type. Based on payment type category, different ticket rounding rules may apply.
`isActive`	`bool`	Gets or sets whether payment type can be used.
`description`	`string`	Payment type description (name).
~~`isChangeable`~~	`bool`	Determines whether it is possible to issue from the payment when the amount to pay is overpaid. Note: not used in current version.

## PaymentTypeCategory Enumeration with the following values:

Value	Description
`cash`	Cash payment type.
`creditCard`	Cashless payment type.
`qrPayment`	QR payment type. Used in Slovak "QR Platby" project.
`other`	Other, non-cash payment type.

## PDADeviceSettings

Name	Type	Is required	Description
`MaxQuantity`	`decimal`	false	Maximal quantity user can specify in single ticket item.
`DefaultFiscalName`	`string`	false	Determines name of fiscal device associated with cash register. Usage of different fiscal device may be conditioned by rights of authorized user.
`OpenedPrices`	`bool`	true	Determines whether user can specify unit price of ticket item different than product's unit price.
`SecretCustomersCardId`	`bool`	true	Determines mode of customer account lookup. If set to `false`, user can select customer accounts from list. If set to `true`, user can only scan bar code/QR code with device builtin camera.
`DefaultOrderEndpointName`	`string`	false	Determines name of order endpoint device associated with cash register. Usage of different order endpoint may be conditioned by rights of authorized user.
`DefaultStockName`	`string`	false	Determines name of stock associated with cash register. Usage of different stock may be conditioned by rights of authorized user.

All other settings are managed directly in the application (PORTOS Mobilný čašník). ## Plu

Property name	Type	Description
`id`	`string`	Unique identifier.
`stockName`	`string`	Name of associated `Stock`.
`code`	`int`	Product's PLU code. Unique within associated `Stock`. Therefore, a combination of the `code` and `stockName` can be used to uniquely identify the PLU.
`codes`	`string[]`	Collection of alternative product codes, barcodes or external system identifiers.
`name`	`string`	Product name. E.g. "Coffee".
`description`	`string?`	Optional full product name. If this value is provided, it is used as display name instead of `name` property. E.g. "Signature Brewed Coffee Blend".
`customerDescription`	`string?`	Full description for customer, containing one or more sentences. Used mostly in menus. E.g. "Indulge in the rich and aromatic essence of our meticulously brewed coffee, a harmonious blend of carefully selected beans for a truly invigorating experience.".
`retailPriceIncludingVat`	`UnitPrice`	The unit price including VAT. Must be positive or zero for `container` plu type.
`vatCategory`	`int`	The category of associated VAT rate.
`articleCategoryLabel`	`string`	The label of associated article category.
`orderEndpointNames`	`string[]`	The collection of order endpoint names. When product is ordered by customer, order is sent to all order endpoints listed in this collection that are marked as active.
`courseNumber`	`int?`	Specifies default course number for given product. Used to determine the order of food and drinks brought to the table.
`unit`	`string`	Up to three characters long measurement unit.
`type`	`PluType`	Type of product.
`stockQuantity`	`Quantity?`	This field indicates the total count of physical units currently available in inventory. Exclusively for PLUs categorized as material type.
`minStockQuantity`	`Quantity?`	Minimal stock quantity treshold. Defines the minimum acceptable quantity of physical units. When the available inventory falls below this threshold, users can receive notifications to take necessary actions. Exclusively for PLUs categorized as material type.
`stockValue`	`UnitPrice?`	The stock value excluding VAT. Exclusively for PLUs categorized as material type.
`lastPurchasePrice`	`UnitPrice?`	Last purchase price excluding VAT. Exclusively for PLUs categorized as material type. This value is automatically updated by server after each product purchase (based on created StockTransfer).
`receipt`	`PluReceiptItem[]`	Items of PLU recipe. Exclusively for PLUs categorized as `Recipe` type.
`pluPriceHistory`	`PluPriceHistoryItem[]`	Collection that tracks retail price changes.
`color`	`string?`	The RGB color code associated with this PLU, which is displayed within the cash register application. This feature aids in convenient visual identification, facilitating efficient lookups.
`isSplittable`	`bool`	If set to `false`, this PLU can only be sold in whole integer quantities, without the option for fractional or partial units.
`isDiscountAllowed`	`bool`	Determines whether discount can be placed on ticket item associated with this PLU. Must be false for `container` plu type.
`isActive`	`bool`	Determines whether this PLU is accessible in cash register. If given product or service is not available, associated PLU can be marked as inactive. This is alternative approach to PLU deletion.
`isPriceFixed`	`bool`	Determines whether unit price for ticket items associated with this PLU can be adjusted. Howewer, price change must be allowed in device settings as well.
`isCashbackAllowed`	`bool`	Determines whether cashback can be provided for purchase of this PLU. When enabled, customers may receive cashback as part of their purchase. The purchase must be associated with Customer with positive, non-zero `creditRate` (cashback rate).
`isFavorite`	`bool`	This attribute indicates whether the given product is registered as a favorite, enabling easier retrieval within the cash register system.
`sortHint`	`int?`	This optional attribute serves as a hint for sorting articles within the cash register application, aiding in the organization and arrangement of items.
`specialRegulation`	`TaxFreeReason?`	This attribute signifies the justification for applying a zero VAT rate to this PLU, if the rationale matches with one of the reasons defined in `TaxFreeReason` enumeration. `null` otherwise.
`packaging`	`PluPackaging?`	Information related to PLU packaging.
`images`	`PluImage[]`?	Optional PLU images.
`purchaseTypes`	`PluPurchaseType[]?`	Purchase types settings for this product.
`ordering`	`PluOrderingItem[]?`	Information related to PLU ordering, based on `OrderOrigin`.
`modifiers`	`PluModifier[]?`	Collection of Modifier references associated with given PLU.
`allergens`	`Allergen[]?`	A list of potential allergenic substances included in the product, helping users identify allergy risks.
`additives`	`Additive[]?`	A collection of chemicals or substances added to preserve or enhance flavor, appearance, or other qualities.
`ingredients`	`PluIngredient[]?`	Detailed list of components used in the product, providing transparency for consumers about what the product contains.
`nutritionalInfo`	`PluNutritionalInfo?`	Data about the nutritional content of the product.
`manufacturer`	`PluManufacturer?`	The information related to the company that produces the product.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## PluId Plu can be uniquely identified using either `id` or combination of `code` and `stockName`.

Property name	Type	Description
`code`	`int`	Plu's `code` property.
`stockName`	`string`	Plu's `stockName` property.

## PluImage

Property name	Type	Description
`url`	`string`	String which identifies one or more image candidate strings, separated using commas (,) each specifying image resources to use under given circumstances. Each image candidate string contains an image URL and an optional width or pixel density descriptor that indicates the conditions under which that candidate should be used. Please refer to https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset for more information.
`alt`	`string?`	Optional field. Provides fallback (alternate) text to display when the image is not loaded. Please refer to https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt for more information.

## PluIngredient

Property name	Type	Description
`Name`	`string`	Represents the name of the ingredient.

## PluManufacturer

Property name	Type	Description
`Name`	`string?`	The name of the manufacturer.
`Brand`	`string?`	The name of the brand.
`CountryOfOrigin`	`string?`	Where the item originated from.

## PluModifier

Property name	Type	Description
`id`	`string`	Unique modifier identifier.

## PluNutritionalInfo

Property name	Type	Description
`alcoholPercentage`	`decimal?`	Represents alcohol by volume (ABV). Water has an alcoholic strength of 0% ABV, while pure alcohol is 100% ABV. For example, 5.0 for 5%.
`caffeine`	`MeasureQuantity?`	Caffeine content (per 100ml).
`Energy`	`EnergyValue?`	Represents the energy value.

## PluOrderingItem Settings for product ([`PLU`](#plu)) ordering related to specific [`OrderOrigin`](#orderorigin).

Property name	Type	Description
`orderOrigin`	`OrderOrigin`	Order origin associated with this item.
`enabled`	`bool`	Determines whether given type of order origin is enabled for associated PLU.
`paused`	`bool`	Determines whether given type of order origin is temporarily paused (e.g. due to high demand or due to machine failure).

## PluPackaging

Property name	Type	Description
`volume`	`MeasureQuantity?`	Specifies the volume of the product within its packaging. Value must have positive, non-zero amount.
`weight`	`MeasureQuantity?`	Specifies the weight of the product packaging. Value must have positive, non-zero amount and weight unit (`g`, `dag` or `kg`).
`packagePluId`	`PluId?`	When provided, this attribute specifies the PLU that represents the packaging of associated product.
`usePackagePluOnSale`	`bool`	Enabling this option by setting it to `true` allows the cash register application to automatically include the packaging PLU (determined by `packagePluId` when the associated product is sold.
`storageTemperatureCondition`	PluPackagingStorageTemperatureCondition	The storage temperature condition.

## PluPackagingStorageTemperatureCondition This table describes the different storage temperature conditions applicable to products. | Temperature Condition | Description | Slovak Term | | --------------------- | --------------------------------------------------------------------------------------------------- | -------------- | | `frozen` | The product must be kept at or below freezing temperatures (0°C or 32°F). | Mrazené | | `refrigerated` | The product needs to be kept cool, typically between 0°C and 4°C (32°F and 39°F). | Chladené | | `ambient` | The product can be safely stored at room temperature, typically around 20°C to 25°C (68°F to 77°F). | Izbová teplota | | `warm` | The product should be kept warm to maintain its quality and prevent degradation. | Teplé | ## PluPriceHistoryItem

Property name	Type	Description
`date`	`DateTime`	The date and time of retail price change.
`retailPriceIncldingVat`	`UnitPrice`	The new product retail unit price (including VAT).

## PluPurchaseType Settings for product ([`PLU`](#plu)) related to specific [`PurchaseType`](#ticketpurchasetype).

Property name	Type	Description
`purchaseType`	`PurchaseType`	The purchase type associated with this item.
`enabled`	`bool`	Determines whether given type of purchase type is enabled for product.
`vatCategory`	`int`	VAT category that is used for given PurchaseType. Retail price excluding VAT is adjusted, so retail price including VAT is preserved, after given VAT category is applied.

## PluReceiptItem

Property name	Type	Description
`quantity`	`Quantity`	The quantity that should be subtracted from the stock when a single unit of the parent PLU is sold.
`pluId`	`PluId`	Identifier of PLU to be subtracted.
`plu`	`Plu?`	The PLU referenced by `pluId` property. This property is only present if `$include=ReceiptPlu` is specified in GET plus API endpoint.

## PluType Enumeration with the following values:

Value	Is material	Description
`stockItem`	true	Stock item (e.g. ingredient or material). A cover that can be the subject of a deposit and can be repurchased by a trader. This is an material product that has physical representation and associated stock quantity and can be processed in stock takings.
`recipe`	false	Recipe (e.g. meal or complex product) that can reference other recipes, stock items or containers in recipe list. Stock quantity is not tracked for this type of product.
`service`	false	Service that has no physical form and thus stock quantity is not tracked for this type of product.
`container`	true	A container (cover) that can be the subject of a deposit and can be repurchased by a trader. This is an material product that has physical representation and associated stock quantity and can be processed in stock takings.

## Price Used also as an multiplication result of [`Quantity`](#quantity) and [`UnitPrice`](#unitprice) instances.

Property name	Type	Description
`amount`	`decimal`	Up to 2 decimal places.
`currencyLabel`	`string`	3-characters long currency label (ISO 4217).

## PrintPreliminaryTicketContext

Name	Type	Description
`orderEndpointName`	`string`	The name of the order endpoint where the preliminary receipt will be printed.

## PrintTicketFormOptions

Name	Type	Description
`footerText`	`string`	The optional text that is displayed on end of receipt. Only non-control characters are allowed (and CR + LF).

## ProcessOrdersContext

Property name	Type	Description
`ticketIds`	`string[]`	Collection of ticket identifiers. All orders associated with given tickets will be processed.

## ProductLicenseActivation

Property name	Type	Description
`code`	`string`	Activation code.
`license`	`ProductLicenseRequest`	License to be activated.

## ProductLicenseRequest

Property name	Type	Description
`shopId`	`int`	Unique venue identifier.
`features`	`ProductLicenseRequestFeature[]`	List of features.

## ProductLicenseRequestFeature

Name	Type	Description
`productSku`	`string`	The feature identifier.
`rawValue`	`string?`	Value associated with feature.
`name`	`string`	Feature display name.
`activationTime`	`DateTime?`	Activation date and time.
`expirationTime`	`DateTime?`	Expiration date and time.

## PurchaseType Enumeration with the following values:

Value	Description
`unknown`	Purchase type is not specified.
`walkIn`	The purchase is being held at the venue.
`takeAway`	The purchase is being picked up at the venue by customer.
`delivery`	The purchase will be delivered to customer.

## Quantity

Property name	Type	Description
`amount`	`decimal`	Up to 3 decimal places.
`unit`	`string`	Up to 3-characters measurement unit.

## QueryResult This models represents generic response from all API routes that returns collection of resources.

Property name	Type	Description
`items`	`object[]`	Collection of resources that met query criteria.
`count`	`int`	Number of elements in `items` property.
`totalCount`	`int`	Number of total resources available. Value may differ from `count`, when pagination or filtering is applied.

## RecordCopyContext This model is used to specify the ticket for which a copy is going to be printed. The ticket can be specified by providing either its ticket number and daily sales report number (`ticketNumber` and `dailySalesReportNumber` properties), or its ticket number along with the close date of the daily sales report (`ticketNumber` and `dailySalesReportDate` properties).

Name	Type	Description
`ticketNumber`	`int`	Ticket sequence number, unique within associated daily sales report. This value can be found in `ticket.closeInfo.number`.
`dailySalesReportNumber`	`int?`	The number of daily sales report. This value can be found in `ticket.closeInfo.dailySalesReportNumber`.
`dailySalesReportDate`	`DateTime?`	The close date of daily sales report.

## RefreshTokenResult

Name	Type	Description
`tokenId`	`string`	The JWT token using for authenticating requests.
`refreshToken`	`string`	The refresh token.

## Role

Name	Type	Description
`name`	`string`	Unique role identifier.
`label`	`string`	Short label (title).
`description`	`string?`	Optional role description.
`rights`	`string[]`	Collection of user rights associated with given role.
`envNames`	`string[]`	Collection of device environments, for which given role can be associated to user.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## Session

Name	Type	Description
`sessionId`	`string`	Unique session identifier.
`identity`	`SessionIdentity`	Information about user associated with given session.
`startedAt`	`DateTime?`	Date and time when session was issued.
`expiresAt`	`DateTime?`	Date and time when session expires.
`lastAccessAt`	`DateTime?`	Date and time of the most recent use of the session to perform an API method.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## SessionIdentity

Name	Type	Description
`userName`	`string`	Unique user name.
`deviceName`	`string`	Name of device user is operating on.
`envName`	`string`	Name of device environment.
`authenticationType`	`string`	Name of authentication scheme.

## Settings This model has no predefined properties. Value of each property may be some primitive type, such as string, bool, integer, decimal, etc. Collection or object values are not allowed. Note: In current version, property names starts with capital letter. ## Stock

Name	Type	Description
`name`	`string`	Unique stock name (abbreviation).
`description`	`string`	Full stock name.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## StockTaking

Name	Type	Description
`id`	`string`	Unique identifier.
`createdAt`	`DateTime`	Date and time of stock taking creation.
`closedAt`	`DateTime?`	Date and time of stock taking closure. If value is `null`, stock taking is not closed and can be edited or deleted. When value is not `null`, the `closedBy` property must be provided as well.
createdBy	`UserInfo`	Information about user who created this stock taking.
`closedBy`	`UserInfo?`	Information about user who closed this stock taking. If value is `null`, stock taking is not closed and can be edited or deleted. When value is not `null`, the `closedAt` property must be provided as well.
`currencyLabel`	`string`	Label of currency in which stock taking financial operations are calculated.
items	`StockTakingItem[]`	This collection includes products on which stock quantity corrections are performed
`_v`	`int`	Resource version. This property is tracked and updated by API.

## StockTakingItem

Name	Type	Description
`expectedQuantity`	`Quantity`	The expected stock quantity of product.
`actualQuantity`	`Quantity?`	The actual stock quantity determined by stock taking.
`plu`	`StockTakingItemPlu`	The information about associated product (`Plu`).

## StockTakingItemPlu

Name	Type	Description
`name`	`string`	Product's name
`code`	`int`	Product's code
`codes`	`string[]`	Collection of alternative product codes.
`stockName`	`string`	Name of `Stock` associated with product (`Plu`).
`articleCategoryLabel`	`string`	Label of article category associated with product (`Plu`).
`vat`	`VatInfo`	Vat information associated with product (`Plu`).
`unitPurchasePrice`	`UnitPrice`	Product's unit purchase price.
`unitRetailPrice`	`UnitPrice`	Product's unit retail price.

## StockTransfer

Name	Type	Description
`id`	`string`	Unique identifier.
`type`	`StockTransferType`	Type of stock transfer.
`items`	`StockTransferItem[]`	Items collection.
`payments`	`StockTransferPayment[]`	Payments collection.
`company?`	`StockTransferCompanyInfo`	Stock transfer issuer.
`partner?`	`StockTransferCompanyInfo`	The company that supplies (for `income` type) or purchases (`outcome`, `sale` and `invoice` type) the goods or services.
`createdBy`	`UserInfo`	User that creates this stock transfer.
`createdAt`	`DateTime`	Date and time of stock transfer creation in system.
`closedBy`	`UserInfo?`	Contains information about user who closed this stock transfer. If stock transfer is not closed, value is `null`.
`closedAt`	`DateTime?`	Date and time of stock transfer closing. If stock transfer is not closed, value is `null`.
`dueDate`	`DateTime?`	The date and time when the payment is due.
`documentNumber`	`string?`	The document number. Usually generated by system using format defined by stock transfer numbering associated with stock transfer type.
`documentDate`	`DateTime`	The official document issue date.
`deliveryDate`	`DateTime?`	Delivery date.
`variableSymbol`	`string?`	The reference number that helps automated payment linking.
`constantSymbol`	`string?`	The constant symbol.
`specificSymbol`	`string?`	The specific symbol.
`note`	`string?`	The optional note that is printed on document.
`deliveryType`	`StockTransferDeliveryType`	The type of delivery.
`paymentType`	`StockTransferPaymentType`	The payment method.
`discountRate`	`decimal`	Discount rate. Numeric value between 0 and 100 with precision up to 2 decimal places.
`currencyLabel`	`string`	The currency label.
`meta`	`Meta`	Object that holds additional information related to stock transfer.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## StockTransferCompanyInfo

Name	Type	Description
`name`	`string`	Company name.
`crn`	`string`	Company registration number (known as IČO, in Slovak Republic).
`vatId`	`string?`	VAT ID (known as IČ DPH, in Slovak Republic).
`taxId`	`string?`	TAX ID (known as DIČ, in Slovak Republic).
`isTaxPayer`	`bool`	Gets whether this company is tax payer.
`register`	`string?`	The company's entry in the business register.
`contact`	`Contact?`	Contact associated with company.
`address`	`Address?`	Company invoice address.
`shippingAddress`	`Address?`	Optional company shipping address (if is different than address).
`bankAccount`	`BankAccount?`	Company bank account.

## StockTransferDeliveryType Enumeration with the following values:

Value	Description
`Unknown`	The method of delivery is currently unidentified or unspecified.
`None`	No formal delivery method is associated with the shipment. This could imply that the items might be collected virtually (e.g. software products).
`Cartage`	Delivery transportation method of goods, typically within a localized area. It's often used for short-distance deliveries.
`PostOffice`	The items will be sent via the postal service.
`Courier`	Specialized courier service will be utilized for the shipment.
`PickUp`	The recipient will personally collect the items from a designated location.

## StockTransferItem

Name	Type	Description
`id`	`int`	Identifier of item, unique within stock transfer.
`sourcePlu`	`StockTransferItemPlu?`	The information about source PLU. Used in `outcome`, `transfer`, `sale`, `invoice` and `correction` stock transfer types.
`destinationPlu`	`StockTransferItemPlu?`	The information about destination PLU. Used in `income`, `transfer` and `correction` stock transfer types.
`note`	`string?`	The optional note related to stock given stock transfer item.

## StockTransferItemPlu

Property name	Type	Description
`code`	`int`	Product's PLU code.
`stockName`	`string`	Name of associated `Stock`.
`name`	`string`	Product name. E.g. "Coffee".
`quantity`	`Quantity`	Positive or negative non-zero quantity.
`discountRate`	`decimal`	Discount rate. Numeric value between 0 and 100 with precision up to 2 decimal places.
`isDiscountAllowed`	`bool`	Determines whether discount can be placed on stock transfer item associated with this PLU.
`note`	`string?`	The optional note related to stock given stock transfer item plu.
`receipt`	`StockTransferItemPlu[]`	Items of PLU recipe. Exclusively for PLUs categorized as `Recipe` type.
`type`	`PluType`	Type of product.
`unitPurchasePrice`	`UnitPrice?`	The unit purchase price excluding VAT.
`unitRetailPrice`	`UnitPrice`	The unit retail price excluding VAT.
`vat`	`VatInfo`	The VAT category and VAT rate.

## StockTransferNumbering

Name	Type	Description
`id`	`string`	The unique identifier.
`isActive`	`bool`	Determines whether this numbering can be used to generate stock transfer document numbers.
`type`	`StockTransferType`	Type of stock transfer associated with this numbering.
`format`	`string`	The document number format, e.g. "FA-{yyyy}{i4}". The placeholders enclosed within curly braces (`{` and `}`) are known as "wildcards", dynamically substituted with real values derived from the current sequence number and date. Supported wildcards: `yyyy`: 4 digits year, e.g. 2023. `yy`: 2 digits year, e.g. 23 `MM`: month number, e.g. `08`. `DD`: number of day, e.g. 30. `i4`: 4 digits long sequence number, e.g. 0001. `i6`: 6 digits long sequence number, e.g. 000001. `i8`: 8 digits long sequence number, e.g. 00000001.
`repeat`	`bool`	Determines whehter new numbering intervals can be generated, based on previously active one.
`numberings`	`StockTransferNumberingInterval`	Stores last used number related to specific time interval.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## StockTransferNumberingInterval

Name	Type	Description
`isActive`	`bool`	Determines whether this interval is active and can be used to generate number.
`createdAt`	`DateTime`	Date and time of interval creation.
`startAt`	`DateTime`	Date and time of interval start.
`period`	`StockTransferNumberingIntervalPeriod`	Defines the specific duration for which this interval remains valid.
`currentNumber`	`int`	The next number to be used.

## StockTransferNumberingIntervalPeriod

Name	Type	Description
`unit`	`NumberingPeriodUnit`	The time unit.
`amount`	`int`	The quantity.

## StockTransferPayment

Name	Type	Description
`paymentType`	`StockTransferPaymentType`	The payment method used.
`amount`	`ForeignPrice`	The payment amount.
`paidAt`	`DateTime?`	The date and time of payment, if already settled.
`note`	`string?`	The optional note related to the payment.
`createdAt`	`DateTime`	Date and time of payment creation.
`createdBy`	`UserInfo`	User who created the payment.

## StockTransferPaymentType Enumeration with the following values:

Value	Description
`Unknown`	The specific method of payment is currently unidentified or not provided.
`Cash`	Customer is providing physical currency as the form of payment for the goods or services received.
`BankTransfer`	The electronic transfer of funds directly from the customer's bank account to the recipient's bank account.
`POSTerminal`	Payments made through a point-of-sale (POS) terminal. This could involve debit or credit card transactions, where the customer's card is swiped, inserted, or tapped to process the payment.
`MoneyOrder`	Prepaid payment method where the customer purchases a money order from a financial institution or postal service and then sends it to the recipient.
`CashOnDelivery`	The payment will be made in cash directly to the delivery person upon receipt of the ordered items.
`Coupon`	Refers to using a discount coupon, voucher, or promotional code to cover total cost of the purchase.
`Other`	Payment method that does not fit into the defined categories.

## StockTransferType Enumeration with the following values:

Value	Description
`income`	Income.
`outcome`	Outcome.
`transfer`	Transfer.
`sale`	Sale stock transfer created by system after ticket is closed (similar to outcome).
`invoice`	Invoice (similar to outcome).
`correction`	Sale stock transfer created by system after stock taking is closed.

## TaxFreeReason Describes the reason for assigning zero VAT rate to the product, according to Slovak legislation. Enumeration with the following values:

Value	Description
`vatReverseCharge`	VAT reverse charge.
`vatExemptionGood`	VAT exemption.
`travelAgency`	Special regulation of tax application for travel agencies.
`usedGood`	Special regulation of tax application for used goods.
`artwork`	Special regulation of tax application for works of art.
`collectiblesAndAntiques`	Special regulation of tax application for collectibles and antiques.

## Ticket

Name	Type	Description
`id`	`string`	Unique ticket identifier. If not specified, ID is generated by API.
`externalId`	`string?`	Unique identifier provided by external system.
`state`	`TicketStatus`	State of ticket.
`type`	`TicketType`	Type of ticket.
`name`	`string`	Ticket name (may be given by cashier, and is usually printed on receipt).
`openDate`	`DateTime`	Date and time of ticket creation.
`issueDate`	`DateTime?`	Original date and time of paragon creation, based on which ticket is later created. Required, when `isParagon` is true.
`closeDate`	`DateTime?`	Date and time of ticket closing (receipt printing).
`closeInfo`	`TicketCloseInfo?`	Information about ticket closing. Available only when `state` is `closed`.
`purchaseType`	`PurchaseType`	The type of purchase.
`location`	`TicketLocation?`	Contains information about ticket location, which refers to specific `Table` in `Zone`. May be `null`, if ticket is not associated with any table, or cashier do not use floor plan in cash register application.
`customer`	`TicketCustomerInfo?`	Information about associated customer.
`originDeviceName`	`string?`	Name of device on which ticket was created.
`employee`	`UserInfo`	Cashier assigned to ticket.
`items`	`TicketItem[]`	Collection of products.
`payments`	`TicketPayment[]`	Collection of paments used to pay the purchase.
`currencyLabel`	`string`	Currency label.
`discountRate`	`decimal`	Value between 0 and 100. Up to 2 decimal places.
`roundingAmount`	`Price?`	Rounding amount.
`invoiceNumber`	`string?`	Invoice number. Value is required, if `type` is `invoice`.
`paragonNumber`	`int?`	Sequence number of the paragon based on which the ticket was created. Required, when `isParagon` is `true`.
`isParagon`	`bool`	Specifies whether this ticket represents paragon registration.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## TicketCloseContext

Name	Type	Description
`fiscal`	`TicketCloseContextFiscal`	Fiscal printer options for generating receipt as an result of ticket closing procedure.
`employee`	`UserInfo?`	If an employee is specified, the ticket's closure information will reflect this employee instead of the authenticated user. To specify a user other than the authenticated user, the authenticated user must have the `TicketCloseAs` user right.

## TicketCloseContextFiscal

Name	Type	Description
`name`	`string`	Name of fiscal printer which will perform the ticket closing procedure.
`ticket`	`TicketCloseContextFiscalTicket?`	Ticket closing options.
~~`options`~~	`Settings`	The additional options. Not used in current version.

## TicketCloseContextFiscalTicket

Name	Type	Description
`form`	`TicketForm`	The receipt form, which can be either `print` or `email`.
`formOptions`	`EmailTicketFormOptions` \| `PrintTicketFormOptions`	When the `form` is set to `print`, the type of this property is `PrintTicketFormOptions`. When the `form` is set to `email`, the type of this property is `EmailTicketFormOptions`.

## TicketCloseInfo

Name	Type	Description
`eKasa`	`TicketCloseInfoEKasa?`	Information related to receipt registration in eKasa system. May be null, if used fiscal device do not support eKasa legislation.
`dailySalesReportNumber`	`int`	Number of the daily sales report, which the ticket is associated to.
`number`	`int`	Ticket sequence number, unique within associated daily sales report.
`fiscalMemorySerialNumber`	`string`	Serial number of fiscal memory used in fiscal device. Same fiscal device may have various memories over time (when one fills up).
`fiscalName`	`string`	Unique name of fiscal device used to issue receipt.
`deviceName`	`string`	Unique name of device from which ticket closing was initiated.

## TicketCloseInfoEKasa

Name	Type	Description
`ticketId`	`string`	Unique ticket identifier given by eKasa system.
`ticketForm`	`TicketForm`	Form of receipt.
`ticketFormOptions`	`EmailTicketFormOptions` \| `PrintTicketFormOptions`	Object with string properties containing additional information about ticket form used when creating receipt. When the `ticketForm` is set to `print`, the type of this property is `PrintTicketFormOptions`. When the `form` is set to `email`, the type of this property is `EmailTicketFormOptions`.
`ticketIsOnline`	`bool`	Specifies whether ticket was registered in eKasa system in online mode (`true`) or offline mode (`false`). Offline mode means that internet connectivity was broken at time of receipt registration.

## TicketCustomerInfo

Name	Type	Description
`id`	`string?`
`externalId`	`string?`
`cardSerialNumber`	`string?`
`firstName`	`string?`
`lastName`	`string?`
`fullName`	`string?`
`gender`	`Gender?`
`birthDate`	`DateTime?`
`address`	`CustomerAddress`
`deliveryAddress`	`CustomerAddress`
`isCompany`	`bool`
`company`	`CustomerCompany`
`phone`	`string?`
`email`	`string?`
`creditRate`	`decimal?`
`meta`	`Meta?`

## TicketForm Enumeration with the following values:

Value	Description
`print`	Paper receipt. This is default ticket form.
`email`	Email receipt, also known as "e-receipt".

## TicketItem This class derives from [`TicketItemBase`](#ticketitembase).

Name	Type	Description
`subItems`	`TicketSubItem[]?`	Optional collection of ticket sub items. This property is available from Portos version 4.2.
`referenceFiscalTicketId`	`string?`	Reference to external (fiscal) Ticket identifier. Must have value when `type` is `correction` or `returned`. Must be `null` otherwise. This value can be found in `ticket.closeInfo.eKasa.ticketId`.
`courseNumber`	`int?`	Specifies course number. Can be specified by the cashier to determine the order of food and drinks brought to the table.

**Note:** Remaining properties are documented in the [TicketItemBase](#ticketitembase) section. ## TicketItemBase Base class for [TicketItem](#ticketitem) and TicketSubItem models.

Name	Type	Description
`id`	`uint?`	Ticket item identifier, unique within given ticket.
`externalId`	`string?`	Ticket item external identifier. Supplied by external system.
`type`	`TicketItemType`	Ticket item type. Based on type, restrictions for `quantity` and `unitPrice` are applied.
`plu`	`TicketItemPlu`	Information about associated product.
`comment`	`string?`	Optional comment from cashier.
`unitPrice`	`UnitPrice`	Unit price excluding VAT.
`quantity`	`Quantity`	Quantity
`discountRate`	`decimal`	Discount rate with value between 0 and 100, with precision up to 2 decimal places.
`voucherNumber`	`string?`	Number of voucher. Must have value when `type` is `voucher`. Must be `null` otherwise.
`isQuantityFixed`	`bool?`	Specifies whether `quantity` of this instance can be modified.

## TicketItemPlu

Name	Type	Description
`name`	`string`	Name of product. Displayed in cash register application.
`description`	`string?`	Optional product description. If specified, this value is printed on receipt. Otherwise, `name` is printed on receipt.
`stockName`	`string?`	Stock of product associated with this item.
`code`		Code of product associated with this item.
`articleCategoryLabel`	`string`	Label of article category, to which the product associated with this item belongs.
`vatInfo`	`VatInfo`	VAT rate and VAT category..
`isDiscountAllowed`	`bool`	Determines whether discount can be applied to this product.
`isPriceFixed`	`bool`	Determines whether unit price can be changed by cashier (cashier must operate on device which has allowed price change in its settings).
`isSplittable`	`bool`	If set to `false`, product can be sold only in integer quantities. `true` value means that any quantity can be used.
`orderEndpointNames`	`string[]`	Collection of order endpoints on which each product order is processed.
`type`	`PluType`	Type of product.
`specialRegulation`	`TaxFreeReason?`	The reason of associating zero VAT rate. Value is only provided if one of enumeration option does apply for given product.
`isCashbackAllowed`	`bool`	Determines whether the customer is eligible for a "cash back" for the purchase of this product. Set to `false`, if no cash back should be given or the purchase of this product, `true` otherwise.

## TicketItemType Enumeration with the following values:

Value	Description
`positive`	Ticket item with positive total price (multiplication of unit price and quantity should result to positive or zero value).
`returnedContainer`	Returned product packaging.
`returned`	Returned products.
`correction`	Correction, e.g. after cashier mistake.
`discount`	Discount expressed in absolute value. For relative discounts, use `discountRate` propety of `Ticket` or `TicketItem` models.
`advance`	Deducted advance that was previously paid by purchaser.
`voucher`	Represents deduction of voucher value, when single-purpose voucher is exchanged for provided goods or services.
`credit`	Consumption or top-up of customer credit.
`tip`	Represents a tip given by the customer.

## TicketLocation

Name	Type	Description
`zoneName`	`string`	References unique `Zone` name.
`tableName`	`string`	References table by it's unique name within zone specified by `zoneName` property.

## TicketPayment

Name	Type	Description
`amount`	`ForeignPrice`	Payment amount.
`paymentType`	`TicketPaymentType`	Information about payment type.

## TicketPaymentType

Name	Type	Description
`number`	`int`	Unique payment type number.
`description`	`string`	Payment type human readable description.
`isChangeable`	`bool`	(reserved for future use)
`category`	`PaymentTypeCategory`	Specifies category of payment type.

## TicketStatus Enumeration with the following values:

Value	Description
`open`	Ticket is open and available for modification.
`closed`	Receipt is issued for ticket. Ticket can no longer be modified. This is the final state, as ticket can not be re-opened.

## TicketSubItem Represents a sub-item within a [ticket item](#ticketitem) and derives from [`TicketItemBase`](#ticketitembase). | Property | Type | Description | | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `OptionId` | [`TicketSubItemModifierInfo`](#ticketsubitemmodifierinfo) | Data related to modifier, available when given subitem represents modifier selection. | **Note:** Remaining properties are documented in the [TicketItemBase](#ticketitembase) section. ## TicketSubItemModifierInfo Information related to [`Modifier`](#modifier), based on which [`TicketSubItem`](#ticketsubitem) was created. | Property | Type | Description | | ---------- | -------- | ----------------------------------------------------- | | `Id` | `string` | Unique identifier of the [modifier](#modifier). | | `OptionId` | `string` | Identifier of the [modifier option](#modifieroption). | ## TicketsUpdateAction Specifies update mode for tickets batch update. Enumeration with the following values:

Value	Description
`default`	Default mode.
`move`	Mode, when ticket items are transfered from one ticket to another. Sum of all transfered quantites must equalto zero.

## TicketType Enumeration with the following values:

Value	Description
`cashRegister`	Basic cash register receipt. This is the most common type.
`invalid`	Same as cash register receipt, however this type is used for cashier training. Tax liability does not arise from invalid receipts, when registered in eKasa system.
`invoice`	Represents invoice payment. Ticket of this type must have empty `items` collection.

## TimeOnly The [.NET builtin type](https://learn.microsoft.com/en-us/dotnet/api/system.timeonly). Represents a time of day, as would be read from a clock, within the range 00:00:00 to 23:59:59.9999999. ## TimeOnlyRange

Property name	Type	Description
`from`	`TimeOnly?`	Optional interval start. If value is null, interval starts at 00:00:00.
`to`	`TimeOnly?`	Optional interval start. If value is null, interval ends at 23:59:9999999.

## ToolDeviceSettings No properties are currently defined. Settings are managed directly in PORTOS Link application. ## UnitPrice Similiar to [`Price`](#price), however precision of unit price is up to 6 decimal places.

Property name	Type	Description
`amount`	`decimal`	Up to 6 decimal places.
`currencyLabel`	`string`	3-characters long currency label (ISO 4217).

## UserCreateUpdateContext The context used to create new or update existing [user profile](#userprofile).

Name	Type	Description
`id`	`string`	Unique user ID
`isActive`	`bool`	Determines whether this user profile is active and can be used during authentication.
`isVirtual`	`bool`	Determines whether this user is "virtual user" (virtual users are related to API extensions, and can not be used for authentication).
`name`	`string`	Display name of user.
`userName`	`string`	Unique user name used to log in.
`featureName`	`string?`	Name of "feature" (has value only for virtual users).
`password`	`string?`	The password.
`confirmPassword`	`string?`	The password.
`devices`	`UserDevice[]`	Devices on which the user can be authorized.

## UserDevice

Name	Type	Description
`isActive`	`bool`	Indicates whether user can be authorized on a given device.
`name`	`string`	Unique name of the device on which the user is logged in.
`envName`	`string`	Name of the device environment.
`roles`	`string[]`	Collection of user rights granted when authorized on a given device.
`description`	`string?`	Human readable device description (e.g. "Cash register 1").
`preferences`	`object`	Object containing user-specific preferences for this device. Reserved for future use.

## UserInfo

Property name	Type	Description
`userName`	`string`	Unique user identifier.
`name`	`string`	User display name.

## UserProfile

Name	Type	Description
`id`	`string`	Unique user ID
`isActive`	`bool`	Determines whether this user profile is active and can be used during authentication.
`isVirtual`	`bool`	Determines whether this user is "virtual user" (virtual users are related to API extensions, and can not be used for authentication).
`name`	`string`	Display name of user.
`userName`	`string`	Unique user name used to log in.
`featureName`	`string?`	Name of "feature" (has value only for virtual users).
`hasPassword`	`bool`	Indicates if the given user profile is linked to a password.
`devices`	`UserDevice[]`	Devices on which the user can be authorized.

## UserProfileContext

Name	Type	Description
`id`	`string`	Unique user ID
`isVirtual`	`bool`	Determines whether this user is "virtual user" (virtual users are related to API extensions, and can not be used for authentication).
`name`	`string`	Display name of user.
`userName`	`string`	Unique user name used to log in.
`featureName`	`string?`	Name of "feature" (has value only for virtual users).
`rights`	`string[]`	Collection of user rights that are granted for user authorized on given device.
`device`	`UserProfileContextDevice`	Information about device that user operates on.

## UserProfileContextDevice

Name	Type	Description
`name`	`string`	Unique name of the device on which the user is logged in.
`envName`	`string`	Name of the device environment.
`description`	`string?`	Human readable device description (e.g. "Cash register 1").
`preferences`	`object`	Object containing user-specific preferences for this device. Reserved for future use.
`settings`	`BackOfficeDeviceSettings` \| `CashRegisterDeviceSettings` \| `PDADeviceSettings` \| `ToolDeviceSettings`	An object with string properties, that is used to store device settings. The value of each property within the object corresponds to a specific type based on the `envName` (device environment name).

## Vat VAT category identifier and associated VAT rate.

Property name	Type	Description
`category`	`int`	VAT category identifier. Value between `1` and `10`.
`rate`	`VatRate`	VAT rate. Number with value between 0 and 100 with precision up to 2 decimal places (for taxable items), or `null` (for non-taxable items).
`plannedRateChange`	`VatRateChange?`	Information about the new VAT rate and its effective date. Useful for scenarios where a VAT rate change is scheduled for a specific date and rate.
lastModifiedAt	DateTimeM	The date and time of last update.
`_v`	`int`	Resource version. This property is tracked and updated by API.

## VatIncome

Property name	Type	Description
`vatRate`	`VatRate`	VAT rate. Number with value between 0 and 100 with precision up to 2 decimal places (for taxable items), or `null` (for non-taxable items).
`totalAmount`	`Price`	Total turnover.
`vatAmount`	`Price`	VAT amount.

## VatInfo VAT category identifier and associated VAT rate.

Property name	Type	Description
`category`	`int`	VAT category identifier. Value between `1` and `10`.
`rate`	`VatRate`	VAT rate. Number with value between 0 and 100 with precision up to 2 decimal places (for taxable items), or `null` (for non-taxable items).

## VatRate Represented by nullable decimal value , that contains: * value between 0 and 100 with precision up to 2 decimal places (for taxable items) * `null` (for non-taxable items). Non-taxable items are mostly returnable containers. ## VatRateChange

Property name	Type	Description
`rate`	`VatRate`	VAT rate. Number with value between 0 and 100 with precision up to 2 decimal places (for taxable items), or `null` (for non-taxable items).
`effectiveFrom`	`DateTime`	The date and time when the specified VAT rate takes effect.

## WeeklyScheduleItem Represents a weekly schedule item that can apply to multiple days with optional time ranges.

Property name	Type	Description
`days`	`DayOfWeek[]`	Gets or sets the list of days when the schedule applies. If value is `null` or empty, the schedule is not limited to certain days, and applies every day.
`timeRange`	`TimeOnlyRange?`	Gets or sets the time range for the schedule. If value is `null`, the schedule is not limited by time; starts at the beginning of the day and ends at the end of the day.

## Zone The zone model represents visual representation of a specific area, such as a room, terrace, or any other defined space. It contains the layout, dimensions, and arrangement of objects within that area.

Property name	Type	Description
`name`	`string`	Unique zone identifier.
`defaultFiscalName`	`string?`	Optional name of fiscal device. If not null, all cash register applications should use given fiscal device when printing receipts for tickets associated with given zone.
`items`	`ZoneItem[]`	Collection of zone items (tables or other objects).
`sortHint`	`int?`	Optional sort hint (to order zones in cash register application)
`_v`	`int`	Resource version. This property is tracked and updated by API.

## ZoneItem

Property name	Type	Description
`name`	`string`	Name of zone item, unique within associated zone.
`isTable`	`bool`	Indicates, whether ticket can be associated with given zone item.
`meta`	`ZoneItemMeta`	Meta information related to render given zone item in application user interface.

## ZoneItemMeta

Property name	Type	Description
`position`	`Coordinates`	Specifies center position.
`width`	`decimal`	Non-zero positive element width.
`height`	`decimal`	Non-zero positive element height.
`shape`	`ZoneItemShape`	Element shape.
`rotation`	`int`	Element clockwise rotation in degrees.
`color`	`string`	Color in RGB format, including leading `#` symbol. E.g. `#fff` or `#aabbcc`.

## ZoneItemShape Emumeration defined with the following values:

Value	Description
`circle`	Circle (can also be used for ellipses).
`rectangle`	Rectangle (can be used also for squares) .

# Authentication schemes Following authentication schemes are supported:


		JWT Bearer Authentication	JWT Bearer Authentication
		HMAC Authentication	HMAC Authentication

# JWT Bearer Authentication ## API Methods JWT Token is issued by API after successful login is performed. All subsequent requests have `Authorization` header with value in format `Bearer {tokenId}`. Successful response contains [`AuthResult`](/data-models#authresult) model in response body. ## Authentication `POST` `http://{server-address}/api/auth` User authorization based on provided credentials. User authenticates to specific device, specified by `DeviceName` property in request body. As result, JWT token is issued. #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ------------------------------------------------------ | | UserName\* | string | Unique user name. | | Password | string | User password | | DeviceName\* | string | The unique name of the device the user is logging into | {% tabs %} {% tab title="200: OK Authorization successful" %} ```json { "tokenId": "eyJhbG....GLvNNavSk0A", "refreshToken": "pC73A....63GkAAEpwtWA=", "user": { "id": "635f7ae3072edfeae7c26a1e", "isVirtual": false, "name": "Majiteľ", "userName": "999", "featureName": null, "rights": [ "admin" ], "device": { "name": "P01", "envName": "CashRegister", "description": "P01", "preferences": {}, "settings": { "MaxQuantity": "200", "OpenedPrices": "false", "NoticeOnNegativeSale": "false", "VisibleQuantities": "false", "DefaultFiscalName": "eKasa", "DefaultOrderEndpointName": "", "DefaultStockName": "S01" } } } } ``` {% endtab %} {% tab title="401: Unauthorized Authorization failed" %} ```json { "title": "Nesprávne meno alebo heslo.", "status": 401, "instance": "/api/auth", "errorCode": "Unauthorized", "traceId": "0HMM3ODQRAVOG:00000002" } ``` {% endtab %} {% endtabs %} In case of need, you can get user profile associated with `tokenId`, using request below. Successful response contains [`UserProfileContext`](/data-models#userprofilecontext) model in response body. ## Get current user profile `GET` `http://{server-address}/api/auth` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------- | | Authorization\* | String | JWT token in format `Bearer {tokenId}`. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "id": "635f7ae3072edfeae7c26a1e", "isVirtual": false, "name": "Majiteľ", "userName": "999", "featureName": null, "rights": [ "admin" ], "device": { "name": "P01", "envName": "CashRegister", "description": "P01", "preferences": {}, "settings": { "MaxQuantity": "200", "OpenedPrices": "false", "NoticeOnNegativeSale": "false", "VisibleQuantities": "false", "DefaultFiscalName": "eKasa", "DefaultOrderEndpointName": "", "DefaultStockName": "S01" } } } ``` {% endtab %} {% endtabs %} Each session has its expiration time (may be modified in API settings). To extends lifespan of session, you can call refresh method. Successful response contains [`RefreshTokenResult`](/data-models#refreshtokenresult) model in response body. ## Refresh session `POST` `http://{server-address}/api/auth/refresh` Extends session lifespan. #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | -------------------------------------------- | | tokenId\* | String | Token ID obtained during authorization. | | refreshToken\* | String | Refresh token obtained during authorization. | {% tabs %} {% tab title="200: OK " %} ```javascript { "tokenId": "eyJhbG....GLvNNavSk0A", "refreshToken": "pC73A....63GkAAEpwtWA=" } ``` {% endtab %} {% endtabs %} To sign out and terminate user session, send DELETE request. ## Terminate session `DELETE` `http://{server-address}/api/auth` Logs out user. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------- | | Authorization\* | string | JWT token in format `Bearer {tokenId}`. | {% tabs %} {% tab title="200: OK Always returns OK with empty body." %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} # HMAC Authentication We have developed example projects that illustrate the implementation of HMAC authentication for communication with the PORTOS API. ## PHP The source project and examples can be found in [ninedigit/nws4-php](https://github.com/ninedigit/nws4-php) GitHub project. {% embed url="" %} The NWS4 implementation in PHP {% endembed %} ## .NET C\# The example project for C# can be found in [ninedigit/AspNetCore.Identity.NWS4.Examples](https://github.com/ninedigit/AspNetCore.Identity.NWS4.Examples) GitHub project. {% embed url="" %} The NWS4 examples in C# {% endembed %} Examples are using the `NineDigit.NWS4` library, which can be found as NuGet package at [nuget.org](https://www.nuget.org/packages/NineDigit.NWS4). {% embed url="" %} The NWS4 C# NuGet library {% endembed %} # SignalR The Notification component of Portos API uses SignalR to provide real-time updates to client applications. ## System-defined events Portos API triggers following system-defined events, which can be handled in client applications: | Event | Event name | Description | | ----------------- | -------------------------- | -------------------------------------------------------------- | | Resource changed | `portos.resources.changed` | Raised when resource is changed (created, updated or deleted). | | License activated | `portos.licence.activated` | Raised when Portos license is activated. | ## Receiving Events from Portos API To receive events from the Portos API, the client application must follow these steps: 1. [Configure authentication](#client-authentication) when communicating with SignalR server. 2. [Register an event Handler](#register-event-handler): specify the client application method to invoke when a notification is sent from the Portos API. 3. [Start the connection](#start-the-connection) to SignalR server. 4. [Subscribe to Events](#subscribe-to-events) using the `Subscribe` method, so the Portos API will deliver notifications to the client application. {% hint style="info" %} The code examples below uses JavaScript and [Microsoft's SignalR library](https://learn.microsoft.com/en-us/aspnet/core/signalr/javascript-client). You can install it using npm:

npm install @microsoft/signalr

{% endhint %} ## Client authentication When communicating with SignalR server, client application must be authenticated, as described in [Authentication](/authentication/authentication-schemes) section. Obtained accces token must be used when communication with notification server. ```javascript const token = "YOUR_BEARER_TOKEN"; // Replace with your actual token const serverAddress = "SERVER_ADDRESS"; // Replace with your actual server addess, e.g. http://localhost:3000 const connection = new signalR.HubConnectionBuilder() .withUrl(serverAddress + "/signalr/v1/mainHub", { accessTokenFactory: () => token }) .build(); ``` ## Register Event Handler Use the `connection.on` method to subscribe to the notification events. When a notification is received, the callback function will be executed, and you can handle the notification (e.g., update the UI). ```javascript connection.on("OnEvent", function (message) { // Handle the notification (e.g., update UI) if (message.e == "portos.resources.changed") { // Resource has been changed } else if (message.e == "portos.licence.activated") { // Product license has been activated const newLicense = message.p; } }); ``` The incoming notification is represented by `Notification` class, described below. #### Notification | Property name | Type | Description | | ------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `e` | `string` | Event name, as listed in [System-defined events](#system-defined-events). | | `s` | [`NotificationSender`](#notificationsender) | Information about sender, who sends the message (usually, the server/API). | | `r` | `string?` | Optional notification reference identifier. | | `ca` | `DateTime` | "Created At" ISO8601-formatted string representing date and time of notification creation. | | `ea` | `DateTime?` | "Expires At" Optional ISO8601-formatted string representing date and time of notification expiration. | | `p` | [`License`](/data-models#license) `\| ResourceChangedNotificationPayload` | The notification payload. Based on event, payload may vary. | #### NotificationSender | Property name | Type | Description | | ------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `c` | `string` | Connection identifier. | | `u` | [`NotificationSenderUserIdentity`](#notificationsenderuseridentity) | Information about sender, who performs action resulting in given event. | #### NotificationSenderUserIdentity | Property name | Type | Description | | ------------- | --------- | -------------------------------------------------------------------------------------------------------------------- | | `u` | `string` | Unique user name or "System" for system events. | | `d` | `string` | Name of device, on which user operates on. Or "System" for system events. | | `f` | `string?` |

Feature name.
Specified if source of event is not user, but system module (feature), a.k.a "virtual user".

| #### ResourceChangedNotificationPayload | Property name | Type | Description | | ------------- | ------------------------------- | ------------------------------------------------------------------------------------------- | | `u` | [`UserIdentity`](#useridentity) | | | `n` | `string` | One of system-defined [resource names](/resource-names). | | `a` | `number` |

Numeric identifier for resource action.
1 = Created
2 = Updated
3 = Deleted

Property name	Type	Description
`u`	`string`	Unique user identifier.
`d`	`string`	User display name.
`f`	`string?`	Name of "feature" (has value only for virtual users).

#### ResourceInfo

Property name	Type	Description
`i`	`string`	Unique resource identifier (e.g. database ID).
`n`	`string`	Resource name.
`v`	`number?`	Version of resource.

Example payload for resource changed notification: ```json { "e": "portos.resources.changed", // event name "s": { // sender who sends the notification "c": "connection-identifier", "u": { "u": "SYSTEM", // unique user name "d": "SYSTEM", // device name "f": null // feature name } }, "r": null, // reference ID "ca": "2024-07-01T12:51:52.558Z", // created at "ea": null, // expires at "p": { // notification payload "u": { // user who performed action resulting in resource change "u": "999", // unique user name "d": "BackOffice", // device name "f": null // feature name }, "n": "tickets", // resource name "a": 1, // action (1 = created, 2 = updated, 3 = deleted) "i": { // resource info "i": "573f4511088c772684a738f8", // resource ID "n": "tickets", // resource name "v": 7 // resource version }, "r": [ { ... } // the ticket object ] } } ``` ## Start the connection To start the connection, await the result of the `start` method call. ```javascript // Start the connection await connection.start(); ``` ## Subscribe to Events To subscribe to Portos events, a client application must send a "Subscribe" message containing a payload with the subscription details. In the payload, the client application specifies which [system-defined events](#system-defined-events) to subscribe to. ### Subscribe to Resource Changed Event To subscribe to resource change events, your client application must set `portos.resources.changed` in the payload property's `e` (event name). Optionally, you can also specify a collection of resources. Please refer to the table below: | Property name | Type | Description | | ------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `e` | `string` | The event name. Set to `portos.resources.changed` | | `r` | [`SubscriptionRequestResource`](#subscriptionrequestresource)`[]` | Optional collection of resources that is client application subscribing to. Leave empty to subscribe to all resources. | #### SubscriptionRequestResource | Property name | Type | Description | | ------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `n` | `string` | One of system-defined [resource names](/resource-names). | | `a` | `string[]` |

Optional collection of actions that is client application subscribing to. Leave empty to subscribe to all actions. Allowed values:

- created
- updated
- deleted

| Example:

// Prepare the subscription payload
const subscriptionPayload = {
    e: "portos.resources.changed", // event name
    r: [ // optional collection of resources
        {
            n: "devices", // resource name
            a: [ // optional collection of actions
                "created",
                "updated",
                "deleted"
            ]
        }
    ]
};

// Send the 'Subscribe' message with the payload
await connection.invoke("Subscribe", subscriptionPayload);

### Subscribe to License activated event To subscribe to license activated event, your client application must set `portos.licence.activated` in the payload property `e` (event name). Example: ```javascript // Prepare the subscription payload const subscriptionPayload = { e: "portos.licence.activated" // event name }; // Send the 'Subscribe' message with the payload await connection.invoke("Subscribe", subscriptionPayload); ``` ## Unsubscribe from Events To unsubscribe, invoke the `Unsubscribe` method with the same parameters used for event subscription. ```javascript // Prepare the same payload as for subscription const payload = { e: "portos.licence.activated" // event name }; // Send the 'Unsubscribe' message with the payload await connection.invoke("Unsubscribe", payload); ``` # Webhooks A webhook allows your application to receive real-time notifications when specific events occur. Webhooks can be configured through the PORTOS BackOffice application. For each webhook, you can define the following options: * **URL**: address where the events will be delivered * **Secret**: optional string that is used to create JSON payload signature. * **Resource filter**: specifies list of resources (e.g. tickets, article categories, ...) for which notification will be sent. When an event is triggered, the PORTOS API sends an HTTP POST request to the specified URL, carrying the event data as a JSON payload. It is essential that the external application hosting the URL can handle these HTTP POST requests to process the event data effectively. ## Testing Webhook Deliveries 1. In your browser, navigate to 2. Click **Start a new channel**. Smee.io will generate a unique Webhook Proxy URL for you. 3. Copy the full URL under "**Webhook Proxy URL**". 4. Open PORTOS BackOffice application. 5. Navigate to **System** > **Extensions** > **Webhooks** (or **Systém** > **Rozšírenia** > **Webhooky** if using the Slovak version). 6. Create a new webhook and paste the copied URL from Smee.io into the **Address** (**Adresa**) field. 7. Press the **Save** (**Uložiť**) button 8. In PORTOS BackOffice, perform an action such as creating, editing, or deleting a resource (e.g., an article category). 9. Check your Smee.io channel; the event should appear, confirming that the webhook is working correctly.

Setup an webhook using your smee.io channel URL

The reeived webhook is displayed in your smee.io channel

## Validating Webhook Deliveries To ensure the security and authenticity of webhook deliveries, users have the option to specify a "**secret**" when setting up a webhook. If a secret is defined, every webhook request from your app will include an HTTP header named `X-PORTOS-WEBHOOK-SIGNATURE`. This header contains an HMACSHA256 signature of the JSON payload, generated using the secret. External applications can use this signature to validate that the webhook requests are genuinely from your app and have not been tampered with. ### Example Implementations To implement HMAC verification in your app, please refer to examples below. Examples are using following variables: * `jsonPayload`: The content of the HTTP request body that contains the event data in JSON format. * `receivedSignature` : The value of the `X-PORTOS-WEBHOOK-SIGNATURE` HTTP header, which contains the HMACSHA256 signature sent by the PORTOS API. * `secret`: The secret key specified in webhook settings, used to generate the signature. {% tabs %} {% tab title="C#" %} ```csharp using System.Security.Cryptography; using System.Text; public bool ValidateWebhookSignature(string jsonPayload, string receivedSignature, string secret) { // Convert the secret to a byte array var secretKey = Encoding.UTF8.GetBytes(secret); // Create HMACSHA256 using the secret key using (var hmac = new HMACSHA256(secretKey)) { // Compute the hash of the JSON payload var payloadBytes = Encoding.UTF8.GetBytes(jsonPayload); var computedHash = hmac.ComputeHash(payloadBytes); // Convert the computed hash to a hex string var computedSignature = BitConverter.ToString(computedHash).Replace("-", "").ToLower(); // Compare the computed signature with the received signature return computedSignature == receivedSignature.ToLower(); } } ``` {% endtab %} {% tab title="PHP" %} ```php function validateWebhookSignature($jsonPayload, $receivedSignature, $secret) { // Compute the HMACSHA256 hash of the JSON payload using the secret $computedHash = hash_hmac('sha256', $jsonPayload, $secret); // Compare the computed hash with the received signature return hash_equals($computedHash, $receivedSignature); } ``` {% endtab %} {% tab title="TypeScript" %} ```typescript import * as crypto from 'crypto'; function validateWebhookSignature(jsonPayload: string, receivedSignature: string, secret: string): boolean { // Create HMACSHA256 hash using the secret key const hmac = crypto.createHmac('sha256', secret); hmac.update(jsonPayload); // Compute the hash as a hex string const computedSignature = hmac.digest('hex'); // Compare the computed signature with the received signature return computedSignature === receivedSignature.toLowerCase(); } ``` {% endtab %} {% endtabs %} ### Example Hash calculation Here’s an example of how to calculate the SHA256 hash for a webhook using the provided secret and JSON content: **Secret**: `my-secret-key` **JSON content**: ```json {"id":"c32314f8-39c2-4d03-864e-201586637657","version":"1.0","event":"portos.resources.changed","data":{"user":{"name":"Majiteľ","userName":"999","featureName":null,"deviceName":"BackOffice"},"resourceName":"articleCategories","action":"Updated","resource":{"label":"PIV","description":"Pivá","customerDescription":"","courseNumber":null,"color":"#FF9800","sortHint":null,"tags":[],"ordering":null}}} ``` **Resulting SHA256 hash**: `06324bd73f157373a4a678320a014d8c3db4c2e07d8a6177ecdf233b9f07d3f0` ## Webhook payload ### Data models The webhook content follows this data structure: #### `WebhookPayloadDto` | Name | Type | Description | | --------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Unique webhook identifier (GUID v4 format), generated by PORTOS API. | | `version` | `string` | Indicates version of webhook payload. Currently fixed to "**1.0**" | | `event` | `string` | Name of event. Currently, only *resource changed events* are delivered, so values is fixed to "**portos.resources.changed**" | | `data` | [`WebhookResourceChangedContentDto`](#webhookresourcechangedcontentdto) | Based on value of "event" field, content may vary. | #### `WebhookResourceChangedContentDto` | Name | Type | Description | | -------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user` | [`UserInfoIdentity`](#userinfoidentity)`?` | Information about user that triggers the resource change. | | `action` | `string` | Name of action that represents the resource change. Supported values: **created**, **updated** or **deleted**. | | `resourceName` | `string` | Name of resource, e.g. ticket, articleCategory, ... | | `resource` | `object` | The resource that has been created/updated/deleted. Based on value of "resourceName" field, content may vary (e.g. for "ticket", content is [`Ticket`](/data-models#ticket). | #### `UserInfoIdentity` | Name | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------- | | `name` | `string` | Display name of user. | | `userName` | `string` | Unique user identifier. | | `featureName` | `string` | Name of feature (specified for "virtual" users only, e.g. user representing some Portos extension). | | `deviceName` | `string` | Unique name of the device on which the user operates. | ### Webhook Payload Example {% hint style="info" %} Please note that the actual payload does not include JSON indentation. {% endhint %} ```json { "id": "c32314f8-39c2-4d03-864e-201586637657", "version": "1.0", "event": "portos.resources.changed", "data": { "user": { "name": "Majiteľ", "userName": "999", "featureName": null, "deviceName": "BackOffice" }, "resourceName": "articleCategories", "action": "Updated", "resource": { "label": "PIV", "description": "Pivá", "customerDescription": "", "courseNumber": null, "color": "#FF9800", "sortHint": null, "tags": [], "ordering": null } } } ``` # API keys This page provides a description of the available API routes for managing API keys. API key used in [HMAC authenticaton scheme](/authentication/authentication-schemes/hmac-authentication) and is represented by [`ApiKey`](/data-models#apikey) class. To enable API key usage, the API key must be activated by setting the `isActive` field to true. Once the API key is authorized on the server, the request will be executed within the context of the user specified by their `userName`, operating on the device specified by the `deviceName`. ## API methods ## Get API keys `GET` `http://{server-address}/apikeys` Returns all API keys that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | id | string | Supports NData syntax. | | isActive | bool | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | label | string | Supports NData syn | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "_v": 1, "description": "Daily menu", "label": "MNU", "color": "#AED581", "courseNumber": null, "customerDescription": "Meals according to the daily menu", "sortHint": 1, "tags": [ "Kitchen" ], "ordering": [ { "orderOrigin": "Online", "enabled": true, "weeklySchedule": [ { "days": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" ], "timeRange": { "from": "11:00:00", "to": "13:30:00" } } ] } ] }, { "label": "BRS", "description": "Beers", "customerDescription": null, "courseNumber": null, "color": "#FF8F00", "sortHint": 1, "tags": [], "_v": 1 }, { "label": "SOF", "description": "Soft Drinks", "customerDescription": null, "courseNumber": null, "color": null, "sortHint": null, "tags": [], "_v": 1 } ], "count": 3, "totalCount": 3 } ``` {% endtab %} {% endtabs %} ## Get article category by label `GET` `http://{server-address}/articlecategories/{label}` Result is of type [Article category](/data-models#articlecategory). #### Path Parameters | Name | Type | Description | | --------------------------------------- | ------ | ------------------------------ | | label\* | string | Unique article category label. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "_v": 1, "description": "Daily menu", "label": "MNU", "color": "#AED581", "courseNumber": null, "customerDescription": "Meals according to the daily menu", "sortHint": 1, "tags": [ "Kitchen" ], "ordering": [ { "orderOrigin": "Online", "enabled": true, "weeklySchedule": [ { "days": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" ], "timeRange": { "from": "11:00:00", "to": "13:30:00" } } ] } ] } ``` {% endtab %} {% tab title="404: Not Found Article category with given label is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create article category `POST` `http://{server-address}/articlecategories` Creates new article category. Result is of type [Article category](/data-models#articlecategory). **Required rights** Authorized user must have `ArticleCategoryCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | --------------- | ---------------- | | (body)\* | ArticleCategory | Model to create. | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "_v": 1, "description": "Daily menu", "label": "MNU", "color": "#AED581", "courseNumber": null, "customerDescription": "Meals according to the daily menu", "sortHint": 1, "tags": [ "Kitchen" ], "ordering": [ { "orderOrigin": "Online", "enabled": true, "weeklySchedule": [ { "days": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" ], "timeRange": { "from": "11:00:00", "to": "13:30:00" } } ] } ] } ``` {% endtab %} {% endtabs %} ## Create or update article category `PUT` `http://{server-address}/articlecategories/{label}` Creates new or updates existing article category. Result is of type [Article category](/data-models#articlecategory). **Required rights** Authorized user must have assigned `ArticleCategoryCreate` or `ArticleCategoryUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | --------------------------------------- | ------ | ------------------------------ | | label\* | string | Unique article category label. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | --------------- | -------------------------- | | (body)\* | ArticleCategory | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "_v": 1, "description": "Daily menu", "label": "MNU", "color": "#AED581", "courseNumber": null, "customerDescription": "Meals according to the daily menu", "sortHint": 1, "tags": [ "Kitchen" ], "ordering": [ { "orderOrigin": "Online", "enabled": true, "weeklySchedule": [ { "days": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" ], "timeRange": { "from": "11:00:00", "to": "13:30:00" } } ] } ] } ``` {% endtab %} {% endtabs %} ## Delete article category by label `DELETE` `http://{server-address}/articlecategories/{label}` **Required rights** Authorized user must have `ArticleCategoryDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | --------------------------------------- | ------ | ------------------------------ | | label\* | string | Unique article category label. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "_v": 1, "description": "Daily menu", "label": "MNU", "color": "#AED581", "courseNumber": null, "customerDescription": "Meals according to the daily menu", "sortHint": 1, "tags": [ "Kitchen" ], "ordering": [ { "orderOrigin": "Online", "enabled": true, "weeklySchedule": [ { "days": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" ], "timeRange": { "from": "11:00:00", "to": "13:30:00" } } ] } ] } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Companies This page provides a description of the available API routes for managing companies. Suppliers and purchasers are commonly referred to as companies, and within the companies database, there exists an additional record marked as "*default*" that represents the merchant, owner or the cash register system. Company is represented by [`Company`](/data-models#company) class. ## API methods ## Get companies `GET` `http://{server-address}/companies` Returns all companies that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | id | string | Supports NData syntax. | | crn | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | discountRate | decimal | Supports NData syn | | name | string | Supports NData syntax. | | isDefault | bool | Supports NData syntax. | | isActive | bool | Supports NData syntax. | | isTaxPayer | bool | Supports NData syntax. | | type | CompanyType | Supports NData syntax. | | taxId | string | Supports NData syntax. | | vatId | string | Supports NData syntax. | | dueDays | int | Supports NData syntax. | | search | string | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "62db00718d4c4f2c700bbc5b", "isActive": true, "name": "My supplier", "crn": "123", "vatId": "SK1020304050", "taxId": "1020304050", "isTaxPayer": true, "register": "reg v OR OS Bratislava I, vl.č. 12345/B", "dueDays": 0, "type": "Supplier", "discountRate": 0.0, "isDefault": false, "addresses": [ { "street": "Hlavná 4", "city": "Bratislava", "zipCode": "81101", "country": "Slovensko", "type": "Office" }, { "street": "Dodacia 11", "city": "Bratislava", "zipCode": "81102", "country": "Slovensko", "type": "Shipping" } ], "bankAccounts": [ { "bankCountry": "Slovensko", "bankName": "Tatra banka, a.s.", "iban": "SK0011000000000000000000", "number": null, "swift": "TATRSKBXXXX", "isDefault": true } ], "contacts": [ { "fax": null, "phone": null, "mobile": "+421 900 123 123", "email": "john.doe@suppliercompany.portos", "isDefault": true, "name": "John", "surname": "Doe", "note": null } ], "_v": 1 } ], "count": 1, "totalCount": 1 } ``` {% endtab %} {% endtabs %} ## Get company `GET` `http://{server-address}/companies/{id}` Result is of type [Company](/data-models#company). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "id": "62db00718d4c4f2c700bbc5b", "isActive": true, "name": "My supplier", "crn": "123", "vatId": "SK1020304050", "taxId": "1020304050", "isTaxPayer": true, "register": "reg v OR OS Bratislava I, vl.č. 12345/B", "dueDays": 0, "type": "Supplier", "discountRate": 0.0, "isDefault": false, "addresses": [ { "street": "Hlavná 4", "city": "Bratislava", "zipCode": "81101", "country": "Slovensko", "type": "Office" }, { "street": "Dodacia 11", "city": "Bratislava", "zipCode": "81102", "country": "Slovensko", "type": "Shipping" } ], "bankAccounts": [ { "bankCountry": "Slovensko", "bankName": "Tatra banka, a.s.", "iban": "SK0011000000000000000000", "number": null, "swift": "TATRSKBXXXX", "isDefault": true } ], "contacts": [ { "fax": null, "phone": null, "mobile": "+421 900 123 123", "email": "john.doe@suppliercompany.portos", "isDefault": true, "name": "John", "surname": "Doe", "note": null } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create company `POST` `http://{server-address}/companies` Creates new company. Result is of type [Company](/data-models#company). **Required rights** Authorized user must have `CompanyCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------- | ---------------- | | (body)\* | Company | Model to create. | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "id": "62db00718d4c4f2c700bbc5b", "isActive": true, "name": "My supplier", "crn": "123", "vatId": "SK1020304050", "taxId": "1020304050", "isTaxPayer": true, "register": "reg v OR OS Bratislava I, vl.č. 12345/B", "dueDays": 0, "type": "Supplier", "discountRate": 0.0, "isDefault": false, "addresses": [ { "street": "Hlavná 4", "city": "Bratislava", "zipCode": "81101", "country": "Slovensko", "type": "Office" }, { "street": "Dodacia 11", "city": "Bratislava", "zipCode": "81102", "country": "Slovensko", "type": "Shipping" } ], "bankAccounts": [ { "bankCountry": "Slovensko", "bankName": "Tatra banka, a.s.", "iban": "SK0011000000000000000000", "number": null, "swift": "TATRSKBXXXX", "isDefault": true } ], "contacts": [ { "fax": null, "phone": null, "mobile": "+421 900 123 123", "email": "john.doe@suppliercompany.portos", "isDefault": true, "name": "John", "surname": "Doe", "note": null } ], "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update company `PUT` `http://{server-address}/companies/{id}` Creates new or updates existing company. Result is of type [Company](/data-models#company). **Required rights** Authorized user must have assigned `CompanyCreate` or `CompanyUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------- | -------------------------- | | (body)\* | Company | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "id": "62db00718d4c4f2c700bbc5b", "isActive": true, "name": "My supplier", "crn": "123", "vatId": "SK1020304050", "taxId": "1020304050", "isTaxPayer": true, "register": "reg v OR OS Bratislava I, vl.č. 12345/B", "dueDays": 0, "type": "Supplier", "discountRate": 0.0, "isDefault": false, "addresses": [ { "street": "Hlavná 4", "city": "Bratislava", "zipCode": "81101", "country": "Slovensko", "type": "Office" }, { "street": "Dodacia 11", "city": "Bratislava", "zipCode": "81102", "country": "Slovensko", "type": "Shipping" } ], "bankAccounts": [ { "bankCountry": "Slovensko", "bankName": "Tatra banka, a.s.", "iban": "SK0011000000000000000000", "number": null, "swift": "TATRSKBXXXX", "isDefault": true } ], "contacts": [ { "fax": null, "phone": null, "mobile": "+421 900 123 123", "email": "john.doe@suppliercompany.portos", "isDefault": true, "name": "John", "surname": "Doe", "note": null } ], "_v": 2 } ``` {% endtab %} {% endtabs %} ## Delete company `DELETE` `http://{server-address}/companies/{id}` **Required rights** Authorized user must have `CompanyDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "id": "62db00718d4c4f2c700bbc5b", "isActive": true, "name": "My supplier", "crn": "123", "vatId": "SK1020304050", "taxId": "1020304050", "isTaxPayer": true, "register": "reg v OR OS Bratislava I, vl.č. 12345/B", "dueDays": 0, "type": "Supplier", "discountRate": 0.0, "isDefault": false, "addresses": [ { "street": "Hlavná 4", "city": "Bratislava", "zipCode": "81101", "country": "Slovensko", "type": "Office" }, { "street": "Dodacia 11", "city": "Bratislava", "zipCode": "81102", "country": "Slovensko", "type": "Shipping" } ], "bankAccounts": [ { "bankCountry": "Slovensko", "bankName": "Tatra banka, a.s.", "iban": "SK0011000000000000000000", "number": null, "swift": "TATRSKBXXXX", "isDefault": true } ], "contacts": [ { "fax": null, "phone": null, "mobile": "+421 900 123 123", "email": "john.doe@suppliercompany.portos", "isDefault": true, "name": "John", "surname": "Doe", "note": null } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Currencies This page provides a description of the available API routes for managing currencies. Collection of currencies contains exactly **one** currency marked as domestic. All system transactions are conducted exclusively in the domestic currency. Currency is represented by [`Currency`](/data-models#currency) class. ## API methods ## Get currencies `GET` `http://{server-address}/currencies` Returns all currencies that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | label | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | isDomestic | bool | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "IsDomestic": true, "Label": "EUR", "Sign": "€", "ExchangeRate": 1, "Description": "Euro", "_v": 1 }, { "IsDomestic": false, "Label": "USD", "Sign": "$", "ExchangeRate": 1.1214, "Description": "US Dollar", "_v": 1 }, { "IsDomestic": false, "Label": "CZK", "Sign": null, "ExchangeRate": 23.7529, "Description": "Czech Crown", "_v": 1 } ], "count": 3, "totalCount": 3 } ``` {% endtab %} {% endtabs %} ## Get currency by label `GET` `http://{server-address}/currencies/{label}` Result is of type [Currency](/data-models#currency). #### Path Parameters | Name | Type | Description | | --------------------------------------- | ------ | ---------------------- | | label\* | string | Unique currency label. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "IsDomestic": true, "Label": "EUR", "Sign": "€", "ExchangeRate": 1, "Description": "Euro", "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create currency `POST` `http://{server-address}/currencies` Creates new currency. Result is of type [Currency](/data-models#currency). **Required rights** Authorized user must have `CurrencyCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | ---------------- | | (body)\* | Currency | Model to create. | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "IsDomestic": true, "Label": "EUR", "Sign": "€", "ExchangeRate": 1, "Description": "Euro", "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update currency `PUT` `http://{server-address}/currencies/{label}` Creates new or updates existing currency. Result is of type [Currency](/data-models#currency). **Required rights** Authorized user must have assigned `CurrencyCreate` or `CurrencyUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | --------------------------------------- | ------ | ---------------------- | | label\* | string | Unique currency label. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | -------------------------- | | (body)\* | Currency | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "IsDomestic": true, "Label": "EUR", "Sign": "€", "ExchangeRate": 1, "Description": "Euro", "_v": 2 } ``` {% endtab %} {% endtabs %} ## Delete currency by label `DELETE` `http://{server-address}/currencies/{label}` **Required rights** Authorized user must have `CurrencyDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | --------------------------------------- | ------ | ---------------------- | | label\* | string | Unique currency label. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "IsDomestic": true, "Label": "EUR", "Sign": "€", "ExchangeRate": 1, "Description": "Euro", "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Customers This page provides a description of the available API routes for managing customers. The data model for customer is represented by [`Customer`](/data-models#customer) class. ## API methods ## Get customers `GET` `http://{server-address}/customers` Returns all customers that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CardSerialNumber | string | Supports NData syntax. Compares `SerialNumber` property of elements in `Cards` collection. | | ExternalId | string | Supports NData syntax. | | CreditRate | decimal | Supports NData syntax. | | DiscountRate | decimal | Supports NData syntax. | | IsActive | bool | Supports NData syntax. | | ExpirationTime | DateTime | Supports NData syntax. | | IsExpired | bool | Boolean values allowed. Compares provided value to `Status` property based on `ActivationTime` and `ExpirationTime`. | | Search | string | Value is compared with partial case-insensitive match in following properties: `FirstName`, `LastName`, `Company.Name`, `Company.VatId`, `Company.TaxId` and `Note`. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "customer-id", "externalId": null, "isActive": true, "status": "Valid", "activationTime": null, "expirationTime": null, "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "gender": null, "birthDate": null, "email": "john.doe@portos.sk", "phone": null, "isCompany": false, "company": null, "address": null, "deliveryAddress": null, "credit": { "amount": 0.0, "currencyLabel": null }, "creditTransactions": [], "cards": [ { "externalId": "external-card-id", "isActive": true, "isVirtual": true, "serialNumber": "card-serial-number", "processor": "P", "status": "Valid", "statusTime": null, "statusReason": null, "activationTime": "2022-11-01T00:00:00.00Z", "expirationTime": null, "note": null, "meta": null } ], "creditRate": 0.0, "discountRate": 0.0, "note": null, "meta": {}, "_v": 1 } ], "count": 1, "totalCount": 1 } ``` {% endtab %} {% endtabs %} ## Get customer by ID `GET` `http://{server-address}/customers/{id}` Result is of type [`Customer`](#customer). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | --------------------------- | | id\* | string | Unique customer identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK " %} ```javascript { "id": "customer-id", "externalId": null, "isActive": true, "status": "Valid", "activationTime": null, "expirationTime": null, "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "gender": null, "birthDate": null, "email": "john.doe@portos.sk", "phone": null, "isCompany": false, "company": null, "address": null, "deliveryAddress": null, "credit": { "amount": 0.0, "currencyLabel": null }, "creditTransactions": [], "cards": [ { "externalId": "external-card-id", "isActive": true, "isVirtual": true, "serialNumber": "card-serial-number", "processor": "P", "status": "Valid", "statusTime": null, "statusReason": null, "activationTime": "2022-11-01T00:00:00.00Z", "expirationTime": null, "note": null, "meta": null } ], "creditRate": 0.0, "discountRate": 0.0, "note": null, "meta": {}, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Customer with given ID is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create customer `POST` `http://{server-address}/customers` Creates new customer. Result is of type [`Customer`](#customer). **Required rights** Authorized user must have `CustomerCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | ------------------------ | | (body)\* | Customer | Customer model to create | {% tabs %} {% tab title="201: Created " %} ```javascript { "id": "customer-id", "externalId": null, "isActive": true, "status": "Valid", "activationTime": null, "expirationTime": null, "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "gender": null, "birthDate": null, "email": "john.doe@portos.sk", "phone": null, "isCompany": false, "company": null, "address": null, "deliveryAddress": null, "credit": { "amount": 0.0, "currencyLabel": null }, "creditTransactions": [], "cards": [ { "externalId": "external-card-id", "isActive": true, "isVirtual": true, "serialNumber": "card-serial-number", "processor": "P", "status": "Valid", "statusTime": null, "statusReason": null, "activationTime": "2022-11-01T00:00:00.00Z", "expirationTime": null, "note": null, "meta": null } ], "creditRate": 0.0, "discountRate": 0.0, "note": null, "meta": {}, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update customer `PUT` `http://{server-address}/customers/{id}` Updates existing or creates new customer. Result is of type [`Customer`](#customer). **Required rights** Authorized user must have assigned `CustomerCreate` or `CustomerUpdate` [right](/user-rights). When updating existing customer, additional roles may be required: if `discountRate` property is changed, `CustomerSetDiscount` is required; If `credit` property is changed, `CustomerSetCredit` is required. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | --------------------------- | | id\* | string | Unique customer identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | ----------------------------------- | | (body)\* | Customer | Customer model to create or update. | {% tabs %} {% tab title="200: OK " %} ```javascript { "id": "customer-id", "externalId": null, "isActive": true, "status": "Valid", "activationTime": null, "expirationTime": null, "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "gender": null, "birthDate": null, "email": "john.doe@portos.sk", "phone": null, "isCompany": false, "company": null, "address": null, "deliveryAddress": null, "credit": { "amount": 0.0, "currencyLabel": null }, "creditTransactions": [], "cards": [ { "externalId": "external-card-id", "isActive": true, "isVirtual": true, "serialNumber": "card-serial-number", "processor": "P", "status": "Valid", "statusTime": null, "statusReason": null, "activationTime": "2022-11-01T00:00:00.00Z", "expirationTime": null, "note": null, "meta": null } ], "creditRate": 0.0, "discountRate": 0.0, "note": null, "meta": {}, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Delete customer by ID `DELETE` `http://{server-address}/customers/{id}` **Required rights** Authorized user must have `CustomerDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | --------------------------- | | id\* | string | Unique customer identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK " %} ```javascript { "id": "customer-id", "externalId": null, "isActive": true, "status": "Valid", "activationTime": null, "expirationTime": null, "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "gender": null, "birthDate": null, "email": "john.doe@portos.sk", "phone": null, "isCompany": false, "company": null, "address": null, "deliveryAddress": null, "credit": { "amount": 0.0, "currencyLabel": null }, "creditTransactions": [], "cards": [ { "externalId": "external-card-id", "isActive": true, "isVirtual": true, "serialNumber": "card-serial-number", "processor": "P", "status": "Valid", "statusTime": null, "statusReason": null, "activationTime": "2022-11-01T00:00:00.00Z", "expirationTime": null, "note": null, "meta": null } ], "creditRate": 0.0, "discountRate": 0.0, "note": null, "meta": {}, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found " %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Daily sales reports This page provides a description of the available API routes for managing daily sales reports. The fiscal device sends record closure information after each closed ticket or cash transfer. If a daily sales report record does not already exist (identified by fiscal name, fiscal memory serial number, and daily sales report number), it is automatically created by API. Each ticket is associated with a specific daily sales report, and this information is stored in the [ticket](/data-models#ticket)'s `closeInfo` property. Daily sales report record is modified by API after following actions are performed on fiscal device: * cash transfer: new element is added to cash transfers collection * daily sales report closure: fiscal info model is fulfilled and daily sales report is considered as *closed*. Daily sales report is closed, when it's `state` property is set to `closed` or `manuallyClosed`. Closed daily sales reports cannot be modified. Daily sales report is represented by [`DailySalesReport`](/data-models#dailysalesreport) class. ## API methods ## Get daily sales reports `GET` `http://{server-address}/dailysalesreports` Returns all daily sales reports that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | | isClosed | bool | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | id | bool | Supports NData syntax. | | openDate | DateTime | | | currencyLabel | string | | | fiscalMemorySerialNumber | string | | | number | int | | | fiscalName | string | | | state | DailySalesReportStatus | | | closeDate | DateTime | | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "646f5d625527869ae467b117", "fiscalName": "eKasa", "number": 2, "fiscalMemorySerialNumber": "1326585810", "openDate": "2023-06-28T08:06:40Z", "closeDate": null, "currencyLabel": "EUR", "cashTransfers": [], "fiscalInfo": null, "state": "Open", "_v": 1 }, { "id": "649ad7516413d6a4de6c8cb4", "fiscalName": "eKasa", "number": 1, "fiscalMemorySerialNumber": "1326585810", "openDate": "2023-06-27T08:04:25.605Z", "closeDate": "2023-06-27T22:42:13.662Z", "currencyLabel": "EUR", "cashTransfers": [], "fiscalInfo": { "ticketsCount": 7, "ticketsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "invalidTicketsCount": 0, "invalidTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceTicketsCount": 0, "invoiceTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "positiveTicketItemsCount": 8, "positiveTicketItemsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "returnedContainerTicketItemsCount": 0, "returnedContainerTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "returnedTicketItemsCount": 0, "returnedTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "correctionTicketItemsCount": 0, "correctionTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "discountTicketItemsCount": 0, "discountTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "advanceTicketItemsCount": 0, "advanceTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "creditTicketItemsCount": 0, "creditTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "voucherTicketItemsCount": 0, "voucherTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "vatIncomes": [ { "vatRate": 20.0, "totalAmount": { "amount": 9.45, "currencyLabel": "EUR" }, "vatAmount": { "amount": 1.58, "currencyLabel": "EUR" } }, { "vatRate": 10.0, "totalAmount": { "amount": 71.2, "currencyLabel": "EUR" }, "vatAmount": { "amount": 6.47, "currencyLabel": "EUR" } }, { "vatRate": 0.0, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } }, { "vatRate": null, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } } ], "grandTotalAmountIncludingVat": { "amount": 1619.31, "currencyLabel": "EUR" }, "roundingDown": { "amount": -0.02, "currencyLabel": "EUR" }, "roundingUp": { "amount": 0.02, "currencyLabel": "EUR" } }, "state": "Closed", "_v": 2 } ], "count": 2, "totalCount": 2 } ``` {% endtab %} {% endtabs %} ## Get daily sales report `GET` `http://{server-address}/dailysalesreports/{id}` Result is of type [DailySalesReport](/data-models#dailysalesreport). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "id": "649ad7516413d6a4de6c8cb4", "fiscalName": "eKasa", "number": 1, "fiscalMemorySerialNumber": "1326585810", "openDate": "2023-06-27T08:04:25.605Z", "closeDate": "2023-06-27T22:42:13.662Z", "currencyLabel": "EUR", "cashTransfers": [], "fiscalInfo": { "ticketsCount": 7, "ticketsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "invalidTicketsCount": 0, "invalidTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceTicketsCount": 0, "invoiceTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "positiveTicketItemsCount": 8, "positiveTicketItemsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "returnedContainerTicketItemsCount": 0, "returnedContainerTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "returnedTicketItemsCount": 0, "returnedTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "correctionTicketItemsCount": 0, "correctionTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "discountTicketItemsCount": 0, "discountTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "advanceTicketItemsCount": 0, "advanceTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "creditTicketItemsCount": 0, "creditTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "voucherTicketItemsCount": 0, "voucherTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "vatIncomes": [ { "vatRate": 20.0, "totalAmount": { "amount": 9.45, "currencyLabel": "EUR" }, "vatAmount": { "amount": 1.58, "currencyLabel": "EUR" } }, { "vatRate": 10.0, "totalAmount": { "amount": 71.2, "currencyLabel": "EUR" }, "vatAmount": { "amount": 6.47, "currencyLabel": "EUR" } }, { "vatRate": 0.0, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } }, { "vatRate":null, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } } ], "grandTotalAmountIncludingVat": { "amount": 1619.31, "currencyLabel": "EUR" }, "roundingDown": { "amount": -0.02, "currencyLabel": "EUR" }, "roundingUp": { "amount": 0.02, "currencyLabel": "EUR" } }, "state": "Closed", "_v": 2 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create or update daily sales report `PUT` `http://{server-address}/dailysalesreports/{id}` Creates new or updates existing (non-closed) daily sales report. Result is of type [DailySalesReport](/data-models#dailysalesreport). **Required rights** Authorized user must have assigned `DsrCreate` or `DsrUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ---------------- | -------------------------- | | (body)\* | DailySalesReport | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "id": "649ad7516413d6a4de6c8cb4", "fiscalName": "eKasa", "number": 1, "fiscalMemorySerialNumber": "1326585810", "openDate": "2023-06-27T08:04:25.605Z", "closeDate": "2023-06-27T22:42:13.662Z", "currencyLabel": "EUR", "cashTransfers": [], "fiscalInfo": { "ticketsCount": 7, "ticketsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "invalidTicketsCount": 0, "invalidTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceTicketsCount": 0, "invoiceTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "positiveTicketItemsCount": 8, "positiveTicketItemsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "returnedContainerTicketItemsCount": 0, "returnedContainerTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "returnedTicketItemsCount": 0, "returnedTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "correctionTicketItemsCount": 0, "correctionTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "discountTicketItemsCount": 0, "discountTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "advanceTicketItemsCount": 0, "advanceTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "creditTicketItemsCount": 0, "creditTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "voucherTicketItemsCount": 0, "voucherTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "vatIncomes": [ { "vatRate": 20.0, "totalAmount": { "amount": 9.45, "currencyLabel": "EUR" }, "vatAmount": { "amount": 1.58, "currencyLabel": "EUR" } }, { "vatRate": 10.0, "totalAmount": { "amount": 71.2, "currencyLabel": "EUR" }, "vatAmount": { "amount": 6.47, "currencyLabel": "EUR" } }, { "vatRate": 0.0, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } }, { "vatRate": null, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } } ], "grandTotalAmountIncludingVat": { "amount": 1619.31, "currencyLabel": "EUR" }, "roundingDown": { "amount": -0.02, "currencyLabel": "EUR" }, "roundingUp": { "amount": 0.02, "currencyLabel": "EUR" } }, "state": "Closed", "_v": 2 } ``` {% endtab %} {% tab title="403: Forbidden Attempt to edit closed daily sales report" %} ```json { "title": "Cannot modify daily sales report that is aleady marked as closed.", "status": 403 } ``` {% endtab %} {% endtabs %} ## Manually close daily sales report `POST` `http://{server-address}/dailysalesreports/{id}/close` Changes `state` of daily sales report to `manuallyClosed`. Result is of type [DailySalesReport](/data-models#dailysalesreport). **Required rights** Authorized user must have `dsrCloseManually` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------ | | id | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly updated." %} ```javascript { "id": "646f5d625527869ae467b117", "fiscalName": "eKasa", "number": 2, "fiscalMemorySerialNumber": "1326585810", "openDate": "2023-06-28T08:06:40Z", "closeDate": "2023-06-28T15:06:40Z", "currencyLabel": "EUR", "cashTransfers": [], "fiscalInfo": null, "state": "ManuallyClosed", "_v": 2 } ``` {% endtab %} {% endtabs %} ## Delete daily sales report `DELETE` `http://{server-address}/dailysalesreports/{id}` **Required rights** Authorized user must have `DsrDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "id": "646f5d625527869ae467b117", "fiscalName": "eKasa", "number": 2, "fiscalMemorySerialNumber": "1326585810", "openDate": "2023-06-28T08:06:40Z", "closeDate": null, "currencyLabel": "EUR", "cashTransfers": [], "fiscalInfo": null, "state": "Open", "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Devices This page provides a description of the available API routes for managing devices. In the PORTOS ecosystem, each cash register, mobile cashier, BackOffice, or any other software application is represented by a device that stores its settings and preferences. Device is represented by [`Device`](/data-models#device) class. ## API methods ## Get devices `GET` `http://{server-address}/devices` Returns all devices that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | name | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | isActive | bool | Supports NData syntax. | | envName | string | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "name": "BackOffice", "isActive": true, "envName": "BackOffice", "description": "BackOffice", "roles": [ "admin" ], "preferences": {}, "settings": {}, "_v": 1 }, { "name": "P01", "isActive": true, "envName": "CashRegister", "description": "Pokladnica 1", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount" ], "preferences": {}, "settings": { "MaxQuantity": "50", "OpenedPrices": "false", "DefaultFiscalName": "eKasa", "DefaultOrderEndpointName": "USB", "DefaultStockName": "S01" }, "_v": 10 }, { "name": "PDA1", "isActive": true, "envName": "PDA", "description": "Mobile cashier 1", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "preferences": {}, "settings": { "DefaultFiscalName": "eKasa", "DefaultStockName": "S01" }, "_v": 11 }, { "name": "Link", "isActive": true, "envName": "Tool", "description": "PORTOS Link", "roles": [ "admin" ], "preferences": {}, "settings": {}, "_v": 1 } ], "count": 4, "totalCount": 4 } ``` {% endtab %} {% endtabs %} ## Get device by name `GET` `http://{server-address}/devices/{name}` Result is of type [Device](/data-models#device). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique device name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "name": "BackOffice", "isActive": true, "envName": "BackOffice", "description": "BackOffice", "roles": [ "admin" ], "preferences": {}, "settings": {}, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create device `POST` `http://{server-address}/devices` Creates new device. Result is of type [Device](/data-models#device). **Required rights** Authorized user must have `DeviceCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | ---------------- | | (body)\* | Device | Model to create. | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "name": "BackOffice", "isActive": true, "envName": "BackOffice", "description": "BackOffice", "roles": [ "admin" ], "preferences": {}, "settings": {}, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update device `PUT` `http://{server-address}/devices/{name}` Creates new or updates existing device. Result is of type [Device](/data-models#device). **Required rights** Authorized user must have assigned `DeviceCreate` or `DeviceUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique device name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | -------------------------- | | (body)\* | Device | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "name": "BackOffice", "isActive": true, "envName": "BackOffice", "description": "BackOffice", "roles": [ "admin" ], "preferences": {}, "settings": {}, "_v": 2 } ``` {% endtab %} {% endtabs %} ## Delete device by name `DELETE` `http://{server-address}/devices/{name}` **Required rights** Authorized user must have `DeviceDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique device name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "name": "BackOffice", "isActive": true, "envName": "BackOffice", "description": "BackOffice", "roles": [ "admin" ], "preferences": {}, "settings": {}, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Fiscals This page provides a description of the available API routes for managing fiscal devices. Fiscal device refers to receipt printer that prints cash register receipts (part of *ticket closing* procedure). Fiscal device is represented by [`Fiscal`](/data-models#fiscal) class. ## API methods ### CRUD actions These API methods allow for the management of fiscal resources, including creation, reading, updating, and deletion. ## Get fiscals `GET` `http://{server-address}/fiscals` Returns all fiscals that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | name | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | isActive | bool | Supports NData syntax. | | type | string | Supports NData syntax. | | dkp | string | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```json { "items": [ { "name": "Virtual", "isActive": true, "type": "Virtual", "version": "", "dkp": "88811223344550000", "settings": { "Footer": "Ďakujeme za nákup!" }, "_v": 1 } ], "count": 1, "totalCount": 1 } ``` {% endtab %} {% endtabs %} ## Get fiscal by name `GET` `http://{server-address}/fiscals/{name}` Result is of type [Fiscal](/data-models#fiscal). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```json { "name": "fiscal1", "isActive": true, "type": "Virtual", "version": "", "dkp": "88811223344550000", "settings": { "Footer": "Ďakujeme za nákup!" }, "_v": 1 }{ "name": "fiscal1", "isActive": true, "type": "Virtual", "version": "", "dkp": "88811223344550000", "settings": { "Footer": "Ďakujeme za nákup!" }, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create fiscal `POST` `http://{server-address}/fiscals` Creates new fiscal. Result is of type [Fiscal](/data-models#fiscal). **Required rights** Authorized user must have `FiscalCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | ---------------- | | (body)\* | Fiscal | Model to create. | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "name": "fiscal1", "isActive": true, "type": "Virtual", "version": "", "dkp": "88811223344550000", "settings": { "Footer": "Ďakujeme za nákup!" }, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update fiscal `PUT` `http://{server-address}/fiscals/{name}` Creates new or updates existing fiscal. Result is of type [Fiscal](/data-models#fiscal). **Required rights** Authorized user must have assigned `FiscalCreate` or `FiscalUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | -------------------------- | | (body)\* | Fiscal | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```json { "name": "fiscal1", "isActive": true, "type": "Virtual", "version": "", "dkp": "88811223344550000", "settings": { "Footer": "Ďakujeme za nákup!" }, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Delete fiscal by name `DELETE` `http://{server-address}/fiscals/{name}` **Required rights** Authorized user must have `FiscalDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```json { "name": "fiscal1", "isActive": true, "type": "Virtual", "version": "", "dkp": "88811223344550000", "settings": { "Footer": "Ďakujeme za nákup!" }, "_v": 1 } ``` {% endtab %} {% tab title="403: Forbidden Fiscal device is marked as inactive" %} ```javascript { "title": "Fiskálna tlačiareň 'eKasa' je označená ako neaktívna.", "status": 403 } ``` {% endtab %} {% endtabs %} ### RPC actions These API methods trigger specific actions on fiscal devices. However, it's important to note that depending on the type of fiscal device, some methods may not be supported. Additionally, attempting an action on a fiscal device that is marked as inactive will also result in failure. In both of these cases, making API calls will result in an HTTP status code of 403. ## Open cash drawer `POST` `http://{server-address}/fiscals/{name}/open_drawer` Opens cash drawer on specified device. **Required rights** Authorized user must have `FiscalOpenDrawer` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="204: No Content Drawer successfully opened." %} The response body contains no content. {% endtab %} {% endtabs %} ## Perform cash transfer `POST` `http://{server-address}/fiscals/{name}/cash_transfer` This method performs a cash transfer operation on a fiscal device specified by name. It updates the latest daily sales report for the device or creates a new report if none is currently opened. The updated daily sales report is then returned in the response body. The method accepts [`CashTransfer`](/data-models#cashtransfer) in request body. **Required rights** Authorized user must have `FiscalCashTransfer` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------ | -------------------- | | (body)\* | CashTransfer | Cash transfer model. | {% tabs %} {% tab title="200: OK Cash transfer successfully.created." %}

{% endtab %} {% endtabs %} ## Print ticket copy `POST` `http://{server-address}/fiscals/{name}/print_record_copy` Prints copy of specified ticket on fiscal printer. Method accepts [`RecordCopyContext`](/data-models#recordcopycontext) in request body. **Required rights** Authorized user must have `FiscalPrintRecordCopy` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ----------------- | ------------------------ | | (body)\* | RecordCopyContext | The record copy context. | {% tabs %} {% tab title="204: No Content Ticket copy printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} ## Print last ticket copy `POST` `http://{server-address}/fiscals/{name}/print_last_record_copy` Prints copy of last ticket printed on fiscal printer. **Required rights** Authorized user must have `FiscalPrintRecordCopy` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="204: No Content Ticket copy printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} ## Print overview sales report `POST` `http://{server-address}/fiscals/{name}/print_overview_sales_report` Prints overview sales report on specified fiscal printer. The overview sales report ("*Priebežná uzávierka*", "*Prehľadová uzávierka*" or "X uzávierka" in Slovak) includes financial information on sales from the last daily sales report. **Required rights** Authorized user must have `OverviewSalesReport` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="204: No Content Report printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} ## Print summary interval sales report `POST` `http://{server-address}/fiscals/{name}/print_summary_interval_sales_report` Prints summary interval sales report on specified fiscal printer. The generated report consolidates financial information extracted from multiple daily sales reports. The method accepts [`IntervalSalesReportContext`](/data-models#intervalsalesreportcontext) in request body. **Required rights** Authorized user must have `SummaryIntervalSalesReport` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------------------------- | -------------------------------------------- | | (body)\* | IntervalSalesReportContext | Model that specifies sales reports interval. | {% tabs %} {% tab title="204: No Content Report printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} ## Print detailed interval sales report `POST` `http://{server-address}/fiscals/{name}/print_detailed_interval_sales_report` Prints detailed interval sales report on specified fiscal printer. The generated report consolidates financial information extracted from multiple daily sales reports. The method accepts [`IntervalSalesReportContext`](/data-models#intervalsalesreportcontext) in request body. **Required rights** Authorized user must have `DetailedIntervalSalesReport` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------------------------- | -------------------------------------------- | | (body)\* | IntervalSalesReportContext | Model that specifies sales reports interval. | {% tabs %} {% tab title="204: No Content Report printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} ## Print daily sales report `POST` `http://{server-address}/fiscals/{name}/daily_sales_report` Performs daily sales closure and prints daily sales report on specified fiscal printer. [`DailySalesReport`](/data-models#dailysalesreport) is returned in response body. It's important to note that certain fiscal devices only support one daily sales report per day, while other types of fiscal devices allow multiple closures to be performed within the same day. **Required rights** Authorized user must have `DoDailySalesReport` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Report printed successfully." %} ```json { "id": "649ad7516413d6a4de6c8cb4", "fiscalName": "eKasa", "number": 1, "fiscalMemorySerialNumber": "1326585810", "openDate": "2023-06-27T08:04:25.605Z", "closeDate": "2023-06-27T22:42:13.662Z", "currencyLabel": "EUR", "cashTransfers": [], "fiscalInfo": { "ticketsCount": 7, "ticketsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "invalidTicketsCount": 0, "invalidTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceTicketsCount": 0, "invoiceTicketsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "positiveTicketItemsCount": 8, "positiveTicketItemsAmountIncludingVat": { "amount": 80.65, "currencyLabel": "EUR" }, "returnedContainerTicketItemsCount": 0, "returnedContainerTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "returnedTicketItemsCount": 0, "returnedTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "correctionTicketItemsCount": 0, "correctionTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "discountTicketItemsCount": 0, "discountTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "advanceTicketItemsCount": 0, "advanceTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "creditTicketItemsCount": 0, "creditTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "voucherTicketItemsCount": 0, "voucherTicketItemsAmountIncludingVat": { "amount": 0.0, "currencyLabel": "EUR" }, "vatIncomes": [ { "vatCategory": 1, "vatRate": 20.0, "totalAmount": { "amount": 9.45, "currencyLabel": "EUR" }, "vatAmount": { "amount": 1.58, "currencyLabel": "EUR" } }, { "vatCategory": 2, "vatRate": 10.0, "totalAmount": { "amount": 71.2, "currencyLabel": "EUR" }, "vatAmount": { "amount": 6.47, "currencyLabel": "EUR" } }, { "vatCategory": 3, "vatRate": 0.0, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } }, { "vatCategory": 4, "vatRate": 0.0, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } }, { "vatCategory": 5, "vatRate": 0.0, "totalAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "vatAmount": { "amount": 0.0, "currencyLabel": "EUR" } } ], "grandTotalAmountIncludingVat": { "amount": 1619.31, "currencyLabel": "EUR" }, "roundingDown": { "amount": -0.02, "currencyLabel": "EUR" }, "roundingUp": { "amount": 0.02, "currencyLabel": "EUR" } }, "state": "Closed", "_v": 2 } ``` {% endtab %} {% endtabs %} ## Print daily sales report copy `POST` `http://{server-address}/fiscals/{name}/daily_sales_report_copy` Prints copy of daily sales report associated with given fiscal printer. Method accepts [`DailySalesReportCopyContext`](/data-models#dailysalesreportcopycontext) in request body. **Required rights** Authorized user must have `FiscalPrintDailySalesReportCopy` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ------ | -------------------------- | -------------------------------------------------------- | | (body) | DailySalesReportCopyContex | Context that specifies daily sales report to be printed. | {% tabs %} {% tab title="204: No Content Report copy printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} ## Print last daily sales report copy `POST` `http://{server-address}/fiscals/{name}/last_daily_sales_report_copy` Prints copy of last daily sales report associated with given fiscal printer. **Required rights** Authorized user must have `FiscalPrintDailySalesReportCopy` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="204: No Content Report copy printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} ## Print text `POST` `http://{server-address}/fiscals/{name}/print_nonfiscal_record` Prints text (nonfiscal record) on selected fiscal device. Method accepts [`NonfiscalRecordContext`](/data-models#nonfiscalrecordcontext) in request body. **Required rights** Authorized user must have `PrintNonfiscalRecord` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------- | | name\* | string | Unique fiscal name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ------ | ---------------------- | ------------------------------------------ | | (body) | NonfiscalRecordContext | Context that specifies text to be printed. | {% tabs %} {% tab title="204: No Content Text printed successfully." %} The response body contains no content. {% endtab %} {% endtabs %} # Health check This article describes the health check functionality of the PORTOS API. ## Get health check `GET` `{{server_adddress}}/api/v2/health` This endpoint allows you to get system-wide health check. {% tabs %} {% tab title="200 Health check successfully retrieved." %} ``` { "status": "Unhealthy", "totalDuration": "00:00:00.7933458", "entries": { "diskstorage": { "data": {}, "description": "Minimum configured megabytes for disk C:\\ is 512 but actual free space are 252 megabytes", "duration": "00:00:00.0414471", "status": "Degraded" }, "license": { "data": { "remaningDays": 196, "expirationDate": "2021-05-13T00:00:00" }, "description": "Licencia exspiruje za 196 dní.", "duration": "00:00:00.0000619", "status": "Healthy" }, "fiscalPrinters": { "data": { "entries": [ { "key": "Fiscal2", "result": { "data": {}, "status": "Healthy" } }, { "key": "eKasa", "result": { "data": {}, "description": "Tlačiareň nie je pripravená. Skontrolujte, či je tlačiareň zapnutá a pripojená do chráneného dátového úložiska.", "status": "Degraded" } }, { "key": "Virtual", "result": { "data": {}, "description": "Tlačiareň nie je zastihnuteľná na adrese 'usb-printer' (chyba: PrinterNotOpened).", "status": "Unhealthy" } } ] }, "duration": "00:00:00.7677499", "status": "Unhealthy" }, "orderEndpoints": { "data": { "entries": [ { "key": "Kuchyna", "result": { "data": {}, "description": "Tlačiareň nie je zastihnuteľná na adrese 'usb-printer' (chyba: PrinterNotOpened).", "status": "Unhealthy" } }, { "key": "01", "result": { "data": {}, "status": "Healthy" } } ] }, "duration": "00:00:00.0056070", "status": "Unhealthy" }, "portos.Features.Qerko": { "data": { "displayName": "Qerko" }, "duration": "00:00:00.0113119", "status": "Healthy" } } } ``` {% endtab %} {% endtabs %} The response HTTP status is always 200 for all health report status values. No authorization is required for accessing API health check. ## Response payload The response payload is based on `Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions` library and consists of following classes: ### Health status String enumeration of following values: * `healthy` Indicates that the health check determined that the component was healthy. * `degraded` Indicates that the health check determined that the component was in a degraded state. * `unhealthy` Indicates that the health check determined that the component was unhealthy, or an unhandled exception was thrown while executing the health check. ### Health report The response payload is represented by `HealthReport` class, which contains following properties:

Property	Type	Description
Property		Description
`status`	`HealthStatus`	Represents the aggregate status of all the health checks. The value is most servere status reported by a health check. If no checks were executed, the value is always `healthy`.
`totalDuration`	`string`	Time the health check service took to execute in time span format (`[d.]hh:mm:ss`).
`entries`	`HealthReportEntry[]`	Dictionary map with each executed health check. The keys in this dictionary map the name of each executed health check to a health report data (represented by `HealthReportEntry` class) returned from the corresponding health check.

### Health report entry The values in health report `entries` dictionary map are represented by the `HealthReportEntry` class, which contains following properties: | Property | | Description | | ------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | [`HealthStatus`](#health-status) | Health status of the specific health check. | | `duration` | `string` | Health check execution duration in time span format (`[d.]hh:mm:ss`). | | `description` | `string \| null` | Optional human-readable description of the status of the component that was checked. | | `data` | `object \| null` | Additional key-value pairs describing the health of the component. Structure may vary for each health check. | | `exception` | [`HealthReportException`](#health-report-exception) | Optional exception object representing the exception that was thrown when checking for status (if any). Equal to `null` when `status` is `healthy`. | ### Health report exception Represents information about failed health report check. | | | | | --------- | ---------------- | ---------------------- | | `message` | `string \| null` | The exception message. | ### Health check result Some health checks contains collection of inner health checks. Each element of such collection is represented by the `HealthCheckResult` class, which contains following properties: | Property | | Description | | ------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | [`HealthStatus`](#health-status) | Health status of the specific health check. | | `description` | `string \| null` | Optional human-readable description of the status of the component that was checked. | | `data` | `object \| null` | Additional key-value pairs describing the health of the component. Structure may vary for each health check. | | `exception` | [`HealthReportException`](#health-report-exception) | Optional exception object representing the exception that was thrown when checking for status (if any). Equal to `null` when `status` is `healthy`. | ## Health checks The [health report's](#health-report) `entries` dictionary contains information for all API components such as: * ["core" parts of API](#core-health-checks) * [optional API "features" (known as modules).](#feature-health-checks) ### Core health checks There are following core health report entries: | Name | Entry key name | Note | | --------------- | ---------------- | ------------------- | | Disk storage | `diskstorage` | From version 4.0.36 | | License | `license` | | | Fiscal printers | `fiscalPrinters` | | | Order endpoints | `orderEndpoints` | | #### Disk storage health check Disk storage health check is associated with the `` diskstorage` `` identifier. This health check verifies free space on disk, on which executing assembly (the API service/deamon) is stored. Following table explains relationship between free megabytes and health status of health check. | Health status | Free megabytes | | ------------- | -------------- | | `healthy` | 512 or more | | `degraded` | Less than 512 | #### License health check License health check is associated with the `license` identifier. License health check verifies expiration date of product license. Following table explains relationship between remaining license days and health status of license health check. | Health status | Remaining license days | | ------------- | ---------------------- | | `healthy` | More than 14 | | `degraded` | Up to 14 | | `unhealthy` | 0 | The `data` section contains following values: | Property name | Description | | ---------------- | ------------------------------------------------- | | `remainingDays` | The number of days to license expiration. | | `expirationDate` | The license expiration date (in iso 8601 format). | The keys may not be present, if `exception` property of license health report entry is set. #### Fiscal printers health check Fiscal printers health check is associated with the `fiscalPrinters` identifier. Checks health of every fiscal device marked as active. The `data` section contains following values: | Property name | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `entries` | The collection of `FiscalPrintersHealthCheckResultEntry`. Each element represents health check result for one fiscal device. | The `FiscalPrintersHealthCheckResultEntry` class contains following properties: | Property name | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------- | | `Key` | The unique fiscal name. | | `Result` | The data describing the health of fiscal device, represented by [`HealthCheckResult`](#health-check-result) class. | #### Order endpoints health check Order endpoints health check is associated with the `orderEndpoints` identifier. Checks health of every order endpoint device marked as active. The `data` section contains following values: | Property name | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `entries` | The collection of `OrderEndpointsHealthCheckResultEntry`. Each element represents health check result for one order endpoint device. | The `OrderEndpointsHealthCheckResultEntry` class contains following properties: | Property name | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------- | | `Key` | The unique order endpoint name. | | `Result` | The data describing the health of order endpoint device, represented by [`HealthCheckResult`](#health-check-result) class. | ### Feature health checks If some optional features are enabled on API server, health report contains report entries for such feature. Name of health report entry is equal to feature name, that is prefixed with `portos.Features` prefix (e.g. `Qerko` feature is associated with report entry with name `portos.Features.Qerko`) and contains `displayName` property in it's `data`. # License License API methods are whitelisted during authorization procedure, allowing them to be accessed without requiring authorization. ## API methods ## Get product license `GET` `http://{server-address}/license` Result is of type [`License`](/data-models#license). {% tabs %} {% tab title="200: OK License information" %} ```json { "shopId": 123456, "activationTime": "2022-03-29T11:38:06Z", "expirationTime": "2030-02-23T23:00:00Z", "verificationTime": "2023-07-17T08:53:41.685Z", "verificationInterval": "1.00:00:00", "features": [ { "productSku": "MaxDeviceCount", "rawValue": "2", "name": "Maximálny počet súčasne pripojiteľných zariadení.", "activationTime": "2021-03-12T14:37:55Z", "expirationTime": "2022-03-10T23:00:00Z" }, { "productSku": "DKPs", "rawValue": "88812345678900001,88811223344550000", "name": "Zoznam kódov on-line registračných pokladníc", "activationTime": "2021-03-12T14:37:55Z", "expirationTime": "2022-03-10T23:00:00Z" } ], "remainingDays": 2413, "isExpired": false } ``` {% endtab %} {% endtabs %} ## Get license request code `POST` `http://{server-address}/license/getrequestcode` The request code is used to request an activation code from the licensing authority, which is then used to activate a license. This API provides a means to retrieve the request code. Subsequently, the licensing authority generates the corresponding activation code based on the provided request code. The method accepts [`ProductLicenseRequest`](/data-models#productlicenserequest) in request body. Response body contains string representing license request code. #### Request Body | Name | Type | Description | | ---------------------------------- | --------------------- | ----------- | | \* | ProductLicenseRequest | | {% tabs %} {% tab title="200: OK License request code" %} ```json "this-is-an-example-request-code" ``` {% endtab %} {% endtabs %} ## Activate license using activation code `POST` `http://{server-address}/license/activate` The method accepts [`ProductLicenseActivation`](/data-models#productlicenseactivation) in request body. Response body contains [`License`](/data-models#license) model. #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------------------ | ----------- | | (body)\* | ProductLicenseActivation | | {% tabs %} {% tab title="200: OK Activated license information" %} ```json { "shopId": 123456, "activationTime": "2022-03-29T11:38:06Z", "expirationTime": "2030-02-23T23:00:00Z", "verificationTime": "2023-07-17T08:53:41.685Z", "verificationInterval": "1.00:00:00", "features": [ { "productSku": "MaxDeviceCount", "rawValue": "2", "name": "Maximálny počet súčasne pripojiteľných zariadení.", "activationTime": "2021-03-12T14:37:55Z", "expirationTime": "2022-03-10T23:00:00Z" }, { "productSku": "DKPs", "rawValue": "88812345678900001,88811223344550000", "name": "Zoznam kódov on-line registračných pokladníc", "activationTime": "2021-03-12T14:37:55Z", "expirationTime": "2022-03-10T23:00:00Z" } ], "remainingDays": 2413, "isExpired": false } ``` {% endtab %} {% endtabs %} # Modifiers This page provides a description of the available API routes for managing modifiers. The data model for modifier is represented by [`Modifier`](/data-models#modifier) class. ## API methods ## Get modifiers `GET` `http://{server-address}/modifiers` Returns all modifiers that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------ | | Id | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | Name | string | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "657b20bbde0bfde5af0f59dd", "name": "Steak doneness", "displayName": "How do you like your steak cooked?", "minimumSelectedOptionsCount": 1, "maximumSelectedOptionsCount": 1, "maximumSelectedOptionsTotalQuantity": 1, "options": [ { "id": "c0b15868-bc3d-4c63-bf58-8b0a47a613c9", "name": "Rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "0f74604d-8eeb-4c35-8f07-91730c7a80da", "name": "Medium rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 1, "maximumSelectedQuantity": 1 }, { "id": "e39889b9-3f1a-4f07-9d90-97edc1f8623c", "name": "Medium", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "fcbad5e7-5e45-415c-bc02-90a2d5c4818c", "name": "Medium well", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "a2b6b6de-6a87-40a0-9d10-4be83314e5dd", "name": "Well done", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 } ], "_v": 1 }, { "id": "65847589d77a632b9674c99c", "name": "side dishes for meat", "displayName": "Add a side", "minimumSelectedOptionsCount": 1, "maximumSelectedOptionsCount": 2, "maximumSelectedOptionsTotalQuantity": 2, "options": [ { "id": "c0b15868-bc3d-4c63-bf58-8b0a47a613c1", "name": "Mashed Potatoes", "unitPrice": { "amount": 4.90, "currencyLabel": "EUR" }, "isUnitPriceIncludingVat": true, "pluId": { "code": 2, "stockName": "S01" }, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": null }, { "id": "0f74604d-8eeb-4c35-8f07-91730c7a80d5", "name": "Grilled Vegetables", "unitPrice": { "amount": 4.70, "currencyLabel": "EUR" }, "isUnitPriceIncludingVat": true, "pluId": { "code": 3, "stockName": "S01" }, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": null } ], "_v": 7 } ], "count": 2, "totalCount": 2 } ``` {% endtab %} {% endtabs %} ## Get modifier by ID `GET` `http://{server-address}/modifiers/{id}` Result is of type [`Modifier`](/data-models#modifier). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | --------------------------- | | id\* | string | Unique modifier identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource with given ID is found." %} ```javascript { "id": "657b20bbde0bfde5af0f59dd", "name": "Steak doneness", "displayName": "How do you like your steak cooked?", "minimumSelectedOptionsCount": 1, "maximumSelectedOptionsCount": 1, "maximumSelectedOptionsTotalQuantity": 1, "options": [ { "id": "c0b15868-bc3d-4c63-bf58-8b0a47a613c9", "name": "Rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "0f74604d-8eeb-4c35-8f07-91730c7a80da", "name": "Medium rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 1, "maximumSelectedQuantity": 1 }, { "id": "e39889b9-3f1a-4f07-9d90-97edc1f8623c", "name": "Medium", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "fcbad5e7-5e45-415c-bc02-90a2d5c4818c", "name": "Medium well", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "a2b6b6de-6a87-40a0-9d10-4be83314e5dd", "name": "Well done", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Resource with given ID is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create modifier `POST` `http://{server-address}/modifiers` Creates new modifier. Result is of type [`Modifier`](/data-models#modifier). **Required rights** Authorized user must have `ModifierCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | --------------- | | (body)\* | Modifier | Model to create | {% tabs %} {% tab title="201: Created " %} ```javascript { "id": "657b20bbde0bfde5af0f59dd", "name": "Steak doneness", "displayName": "How do you like your steak cooked?", "minimumSelectedOptionsCount": 1, "maximumSelectedOptionsCount": 1, "maximumSelectedOptionsTotalQuantity": 1, "options": [ { "id": "c0b15868-bc3d-4c63-bf58-8b0a47a613c9", "name": "Rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "0f74604d-8eeb-4c35-8f07-91730c7a80da", "name": "Medium rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 1, "maximumSelectedQuantity": 1 }, { "id": "e39889b9-3f1a-4f07-9d90-97edc1f8623c", "name": "Medium", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "fcbad5e7-5e45-415c-bc02-90a2d5c4818c", "name": "Medium well", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "a2b6b6de-6a87-40a0-9d10-4be83314e5dd", "name": "Well done", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 } ], "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update modifier `PUT` `http://{server-address}/modifiers/{id}` Updates existing or creates new modifier. Result is of type [`Modifier`](/data-models#modifier). **Required rights** Authorized user must have assigned `ModifierCreate` or `ModifierUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | --------------------------- | | id\* | string | Unique modifier identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | ----------------------------------- | | (body)\* | Modifier | Modifier model to create or update. | {% tabs %} {% tab title="200: OK " %} ```javascript { "id": "657b20bbde0bfde5af0f59dd", "name": "Steak doneness", "displayName": "How do you like your steak cooked?", "minimumSelectedOptionsCount": 1, "maximumSelectedOptionsCount": 1, "maximumSelectedOptionsTotalQuantity": 1, "options": [ { "id": "c0b15868-bc3d-4c63-bf58-8b0a47a613c9", "name": "Rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "0f74604d-8eeb-4c35-8f07-91730c7a80da", "name": "Medium rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 1, "maximumSelectedQuantity": 1 }, { "id": "e39889b9-3f1a-4f07-9d90-97edc1f8623c", "name": "Medium", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "fcbad5e7-5e45-415c-bc02-90a2d5c4818c", "name": "Medium well", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "a2b6b6de-6a87-40a0-9d10-4be83314e5dd", "name": "Well done", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 } ], "_v": 2 } ``` {% endtab %} {% endtabs %} ## Delete modifier by ID `DELETE` `http://{server-address}/modifiers/{id}` **Required rights** Authorized user must have `ModifierDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | --------------------------- | | id\* | string | Unique modifier identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK " %} ```javascript { "id": "657b20bbde0bfde5af0f59dd", "name": "Steak doneness", "displayName": "How do you like your steak cooked?", "minimumSelectedOptionsCount": 1, "maximumSelectedOptionsCount": 1, "maximumSelectedOptionsTotalQuantity": 1, "options": [ { "id": "c0b15868-bc3d-4c63-bf58-8b0a47a613c9", "name": "Rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "0f74604d-8eeb-4c35-8f07-91730c7a80da", "name": "Medium rare", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 1, "maximumSelectedQuantity": 1 }, { "id": "e39889b9-3f1a-4f07-9d90-97edc1f8623c", "name": "Medium", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "fcbad5e7-5e45-415c-bc02-90a2d5c4818c", "name": "Medium well", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 }, { "id": "a2b6b6de-6a87-40a0-9d10-4be83314e5dd", "name": "Well done", "unitPrice": null, "isUnitPriceIncludingVat": true, "pluId": null, "defaultSelectedQuantity": 0, "maximumSelectedQuantity": 1 } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found " %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Order endpoints This page provides a description of the available API routes for managing order endpoint devices. Once the product (PLU) is added to the [`Ticket`](/data-models#ticket), an [`Order`](/data-models#order) is created. Based on product settings, order is sent to one or multiple [order endpoints](/data-models#orderendpoint) for processing. The order endpoint serves as a device that handles incoming orders. This endpoint can take the form of either a printer, such as a kitchen printer, which generates printed instructions for the food preparation team, or a tablet that enables personnel to provide feedback to cashiers once the food is being prepared or is ready for pickup. Order endpoint device is represented by [`OrderEndpoint`](/data-models#orderendpoint) class. ## API methods ## Get order endpoints `GET` `http://{server-address}/orderendpoints` Returns all order endpoints that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | name | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | isActive | bool | Supports NData syntax. | | type | string | Supports NData syntax. | | address | string | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "name": "Kitchen", "isActive": false, "address": "\\\\computer_name\\Kitchen", "type": "SRP350", "settings": { "IsBeepEnabled": "true", "HighlightOrderNumber": "true", "DoubleHeightFont": "true", "DoubleWidthFont": "true" }, "_v": 1 }, { "name": "Pizza", "isActive": false, "address": "\\\\computer_name\\Pizza", "type": "TM88", "settings": {}, "_v": 1 } ], "count": 2, "totalCount": 2 } ``` {% endtab %} {% endtabs %} ## Get order endpoint by name `GET` `http://{server-address}/orderendpoints/{name}` Result is of type [`OrderEndpoint`](/data-models#orderendpoint). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | --------------------------- | | name\* | string | Unique order endpoint name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "name": "Kitchen", "isActive": false, "address": "\\\\computer_name\\Kitchen", "type": "SRP350", "settings": { "IsBeepEnabled": "true", "HighlightOrderNumber": "true", "DoubleHeightFont": "true", "DoubleWidthFont": "true" }, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create order endpoint `POST` `http://{server-address}/orderendpoints` Creates new order endpoint. Result is of type [`OrderEndpoint`](/data-models#orderendpoint). **Required rights** Authorized user must have `OrderEndpointCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------- | ---------------- | | (body)\* | OrderEndpoint | Model to create. | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "name": "Kitchen", "isActive": false, "address": "\\\\computer_name\\Kitchen", "type": "SRP350", "settings": { "IsBeepEnabled": "true", "HighlightOrderNumber": "true", "DoubleHeightFont": "true", "DoubleWidthFont": "true" }, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update order endpoint `PUT` `http://{server-address}/orderendpoints/{name}` Creates new or updates existing order endpoint. Result is of type [`OrderEndpoint`](/data-models#orderendpoint). **Required rights** Authorized user must have assigned `OrderEndpointCreate` or `OrderEndpointUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | --------------------------- | | name\* | string | Unique order endpoint name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------- | -------------------------- | | (body)\* | OrderEndpoint | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "name": "Kitchen", "isActive": false, "address": "\\\\computer_name\\Kitchen", "type": "SRP350", "settings": { "IsBeepEnabled": "true", "HighlightOrderNumber": "true", "DoubleHeightFont": "true", "DoubleWidthFont": "true" }, "_v": 2 } ``` {% endtab %} {% endtabs %} ## Delete order endpoint by name `DELETE` `http://{server-address}/orderendpoints/{name}` **Required rights** Authorized user must have `OrderEndpointDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | --------------------------- | | name\* | string | Unique order endpoint name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "name": "Kitchen", "isActive": false, "address": "\\\\computer_name\\Kitchen", "type": "SRP350", "settings": { "IsBeepEnabled": "true", "HighlightOrderNumber": "true", "DoubleHeightFont": "true", "DoubleWidthFont": "true" }, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Orders This page provides a description of the available API routes for managing orders. After each ticket update, orders are automatically generated. Each order includes contextual information about the products and specifies the order endpoint where the products will be processed. Order is represented by [`Order`](/data-models#order) class. ## API methods ## Get orders `GET` `http://{server-address}/orders` Returns all orders that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | deviceName | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | id | string | Supports NData syntax. | | number | int | Supports NData syntax. | | ticketId | string | Supports NData syntax. | | ticketName | string | Supports NData syntax. | | userUserName | string | Supports NData syntax. | | isProcessed | bool | Supports NData syntax. | | isProcessable | bool | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "64b70e39fa08b1c38bfc5c56", "number": 2, "deviceName": "PDA1", "user": { "name": "Cashier", "userName": "999", "featureName": null }, "ticket": { "id": "64b70d71fa08b1c38bfc5c55", "name": "G-01-01", "location": { "zoneName": "Garden", "tableName": "G-01" }, "purchaseType": "WalkIn", "customer": null, "version": 2 }, "items": [ { "id": 1, "plu": { "name": "Pilsner", "code": 405, "stockName": "S01" }, "quantity": { "amount": 2.0, "unit": "ks" }, "comment": null, "endpoints": [ { "name": "Bar", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.344Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true }, { "id": 2, "plu": { "name": "Chicken wings", "code": 172, "stockName": "S01" }, "quantity": { "amount": 1.0, "unit": "ks" }, "comment": "Extra spicy, please!", "endpoints": [ { "name": "Kitchen", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.346Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true } ], "isProcessed": true, "isProcessable": false } ], "count": 1, "totalCount": 1 } ``` {% endtab %} {% endtabs %} ## Get order `GET` `http://{server-address}/orders/{id}` Result is of type [`Order`](/data-models#order). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------------ | | id\* | string | Unique order identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "id": "64b70e39fa08b1c38bfc5c56", "number": 2, "deviceName": "PDA1", "user": { "name": "Cashier", "userName": "999", "featureName": null }, "ticket": { "id": "64b70d71fa08b1c38bfc5c55", "name": "G-01-01", "location": { "zoneName": "Garden", "tableName": "G-01" }, "purchaseType": "WalkIn", "customer": null, "version": 2 }, "items": [ { "id": 1, "plu": { "name": "Pilsner", "code": 405, "stockName": "S01" }, "quantity": { "amount": 2.0, "unit": "ks" }, "comment": null, "endpoints": [ { "name": "Bar", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.344Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true }, { "id": 2, "plu": { "name": "Chicken wings", "code": 172, "stockName": "S01" }, "quantity": { "amount": 1.0, "unit": "ks" }, "comment": "Extra spicy, please!", "endpoints": [ { "name": "Kitchen", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.346Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true } ], "isProcessed": true, "isProcessable": false } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Process order `POST` `http://{server-address}/orders` Invokes order processing. Method accepts [`ProcessOrdersContext`](/data-models#processorderscontext) in request body, that is used to specify orders to be processed, using [`Ticket`](/data-models#ticket) identifiers. Collection of all affected [`Order`](/data-models#order) models is returned. **Required rights** Authorized user must have `OrderProcess` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------------------- | ----------------------------------- | | (body)\* | ProcessOrdersContext | Conext to specify order processing. | {% tabs %} {% tab title="202: Accepted Order processing is accepted and may continue after API response is sent to caller." %} ```javascript [ { "id": "64b70e39fa08b1c38bfc5c56", "number": 2, "deviceName": "PDA1", "user": { "name": "Cashier", "userName": "999", "featureName": null }, "ticket": { "id": "64b70d71fa08b1c38bfc5c55", "name": "G-01-01", "location": { "zoneName": "Garden", "tableName": "G-01" }, "purchaseType": "WalkIn", "customer": null, "version": 2 }, "items": [ { "id": 1, "plu": { "name": "Pilsner", "code": 405, "stockName": "S01" }, "quantity": { "amount": 2.0, "unit": "ks" }, "comment": null, "endpoints": [ { "name": "Bar", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.344Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true }, { "id": 2, "plu": { "name": "Chicken wings", "code": 172, "stockName": "S01" }, "quantity": { "amount": 1.0, "unit": "ks" }, "comment": "Extra spicy, please!", "endpoints": [ { "name": "Kitchen", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.346Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true } ], "isProcessed": true, "isProcessable": false } ] ``` {% endtab %} {% endtabs %} ## Set order status `POST` `http://{server-address}/orders/{id}/status` Manually changes status for entire order (for all items and all associated order endpoints). Method accepts [`OrderStatusContext`](/data-models#orderstatuscontext) in request body. Updated [`Order`](/data-models#order) is returned. **Required rights** Authorized user must have `OrderUpdate` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ----------------------- | | id\* | string | Order unique identifier | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------------ | ----------- | | (body)\* | OrderStatusContext | | {% tabs %} {% tab title="200: OK Order status updated." %} ```javascript { "id": "64b70e39fa08b1c38bfc5c56", "number": 2, "deviceName": "PDA1", "user": { "name": "Cashier", "userName": "999", "featureName": null }, "ticket": { "id": "64b70d71fa08b1c38bfc5c55", "name": "G-01-01", "location": { "zoneName": "Garden", "tableName": "G-01" }, "purchaseType": "WalkIn", "customer": null, "version": 2 }, "items": [ { "id": 1, "plu": { "name": "Pilsner", "code": 405, "stockName": "S01" }, "quantity": { "amount": 2.0, "unit": "ks" }, "comment": null, "endpoints": [ { "name": "Bar", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.344Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true }, { "id": 2, "plu": { "name": "Chicken wings", "code": 172, "stockName": "S01" }, "quantity": { "amount": 1.0, "unit": "ks" }, "comment": "Extra spicy, please!", "endpoints": [ { "name": "Kitchen", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.346Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true } ], "isProcessed": true, "isProcessable": false } ``` {% endtab %} {% endtabs %} ## Set order item status `POST` `http://{server-address}/orders/{id}/items/{itemId}/status` Manually changes order status for specified [order item](/data-models#orderitem). Status is set for all [order endpoints ](/data-models#orderitemendpoint)associated with given order item. Method accepts [`OrderStatusContext`](/data-models#orderstatuscontext) in request body. Updated [`Order`](/data-models#order) is returned. **Required rights** Authorized user must have `OrderUpdate` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ---------------------------------------- | ------ | ----------------------- | | id\* | string | Order unique identifier | | itemId\* | int | Order item identifier | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ------ | ------------------ | ----------- | | (body) | OrderStatusContext | | {% tabs %} {% tab title="200: OK Order item status updated." %} ```javascript { "id": "64b70e39fa08b1c38bfc5c56", "number": 2, "deviceName": "PDA1", "user": { "name": "Cashier", "userName": "999", "featureName": null }, "ticket": { "id": "64b70d71fa08b1c38bfc5c55", "name": "G-01-01", "location": { "zoneName": "Garden", "tableName": "G-01" }, "purchaseType": "WalkIn", "customer": null, "version": 2 }, "items": [ { "id": 1, "plu": { "name": "Pilsner", "code": 405, "stockName": "S01" }, "quantity": { "amount": 2.0, "unit": "ks" }, "comment": null, "endpoints": [ { "name": "Bar", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.344Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true }, { "id": 2, "plu": { "name": "Chicken wings", "code": 172, "stockName": "S01" }, "quantity": { "amount": 1.0, "unit": "ks" }, "comment": "Extra spicy, please!", "endpoints": [ { "name": "Kitchen", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.346Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true } ], "isProcessed": true, "isProcessable": false } ``` {% endtab %} {% endtabs %} ## Set order endpoint status `POST` `http://{server-address}/orders/{id}/endpoints/{endpointName}/status` Manually change the order status for a specified [order item](/data-models#orderitem) on a specific [order endpoint](/data-models#orderitemendpoint). Method accepts [`OrderStatusContext`](/data-models#orderstatuscontext) in request body. Updated [`Order`](/data-models#order) is returned. **Required rights** Authorized user must have `OrderUpdate` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | ----------------------- | | id\* | string | Order unique identifier | | endpointName\* | string | Order endpoint name | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ------ | ------------------ | ----------- | | (body) | OrderStatusContext | | {% tabs %} {% tab title="200: OK Order endpoint status updated." %} ```javascript { "id": "64b70e39fa08b1c38bfc5c56", "number": 2, "deviceName": "PDA1", "user": { "name": "Cashier", "userName": "999", "featureName": null }, "ticket": { "id": "64b70d71fa08b1c38bfc5c55", "name": "G-01-01", "location": { "zoneName": "Garden", "tableName": "G-01" }, "purchaseType": "WalkIn", "customer": null, "version": 2 }, "items": [ { "id": 1, "plu": { "name": "Pilsner", "code": 405, "stockName": "S01" }, "quantity": { "amount": 2.0, "unit": "ks" }, "comment": null, "endpoints": [ { "name": "Bar", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.344Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true }, { "id": 2, "plu": { "name": "Chicken wings", "code": 172, "stockName": "S01" }, "quantity": { "amount": 1.0, "unit": "ks" }, "comment": "Extra spicy, please!", "endpoints": [ { "name": "Kitchen", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.346Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true } ], "isProcessed": true, "isProcessable": false } ``` {% endtab %} {% endtabs %} ## Delete order `DELETE` `http://{server-address}/orders/{id}` **Required rights** Authorized user must have `OrderDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------------ | | id\* | string | Unique order identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "id": "64b70e39fa08b1c38bfc5c56", "number": 2, "deviceName": "PDA1", "user": { "name": "Cashier", "userName": "999", "featureName": null }, "ticket": { "id": "64b70d71fa08b1c38bfc5c55", "name": "G-01-01", "location": { "zoneName": "Garden", "tableName": "G-01" }, "purchaseType": "WalkIn", "customer": null, "version": 2 }, "items": [ { "id": 1, "plu": { "name": "Pilsner", "code": 405, "stockName": "S01" }, "quantity": { "amount": 2.0, "unit": "ks" }, "comment": null, "endpoints": [ { "name": "Bar", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.344Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true }, { "id": 2, "plu": { "name": "Chicken wings", "code": 172, "stockName": "S01" }, "quantity": { "amount": 1.0, "unit": "ks" }, "comment": "Extra spicy, please!", "endpoints": [ { "name": "Kitchen", "statusChanges": [ { "status": "Created", "date": "2023-07-18T13:12:09.346Z" }, { "status": "Processed", "date": "2023-07-18T13:12:09.706Z" } ], "orderItemStatus": "Processed", "isProcessed": true, "isProcessable": false } ], "courseNumber": null, "isProcessable": false, "isProcessed": true } ], "isProcessed": true, "isProcessable": false } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Payment types This page provides a description of the available API routes for managing payment types. Each purchase has to be paid using various methods, including cash, payment cards, vouchers, and more. These payment methods are collectively referred to as "payment types" and are represented by the [`PaymentType`](/data-models#paymenttype) class. ## API methods ## Get payment types `GET` `http://{server-address}/paymenttypes` Returns all payment types that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | number | int | Supports NData syntax. | | isActive | bool | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | category | PaymentTypeCategory | Supports NData syntax. | | isChangeable | bool | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "number": 1, "category": "Cash", "isActive": true, "description": "Hotovosť", "isChangeable": true, "_v": 1 }, { "number": 2, "category": "CreditCard", "isActive": true, "description": "Platobná karta", "isChangeable": false, "_v": 2 }, { "number": 3, "category": "Other", "isActive": false, "description": "Šek", "isChangeable": false, "_v": 1 }, { "number": 4, "category": "Other", "isActive": false, "description": "Gastrolístky", "isChangeable": false, "_v": 1 }, { "number": 5, "category": "Other", "isActive": false, "description": "Iné", "isChangeable": false, "_v": 1 }, { "number": 6, "category": "Other", "isActive": true, "description": "Wolt", "isChangeable": false, "_v": 2 }, { "number": 7, "category": "Other", "isActive": true, "description": "Bolt", "isChangeable": false, "_v": 1 }, { "number": 8, "category": "Other", "isActive": true, "description": "Foodora", "isChangeable": false, "_v": 2 }, { "number": 9, "category": "Other", "isActive": true, "description": "Bistro.sk", "isChangeable": false, "_v": 2 }, { "number": 10, "category": "Other", "isActive": false, "description": "Adaptee", "isChangeable": false, "_v": 1 } ], "count": 10, "totalCount": 10 } ``` {% endtab %} {% endtabs %} ## Get payment type by number `GET` `http://{server-address}/paymenttypes/{number}` Result is of type [PaymentType](/data-models#paymenttype). #### Path Parameters | Name | Type | Description | | ---------------------------------------- | ---- | --------------------------- | | number\* | int | Unique payment type number. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "number": 1, "category": "Cash", "isActive": true, "description": "Hotovosť", "isChangeable": true, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Payment type with given number is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create payment type `POST` `http://{server-address}/paymenttypes` Creates new payment type. Result is of type [PaymentType](/data-models#paymenttype). **Required rights** Authorized user must have `PaymentTypeCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ----------- | --------------- | | (body)\* | PaymentType | Model to create | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "number": 1, "category": "Cash", "isActive": true, "description": "Hotovosť", "isChangeable": true, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update payment type `PUT` `http://{server-address}/paymenttypes/{number}` Updates existing or creates new payment type. Result is of type [PaymentType](/data-models#paymenttype). **Required rights** Authorized user must have assigned `PaymentTypeCreate` or `PaymentTypeUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | ---------------------------------------- | ---- | --------------------------- | | number\* | int | Unique payment type number. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ----------- | ------------------------------ | | (body)\* | PaymentType | The model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "number": 1, "category": "Cash", "isActive": true, "description": "Hotovosť", "isChangeable": true, "_v": 2 } ``` {% endtab %} {% endtabs %} ## Delete payment type by number `DELETE` `http://{server-address}/paymenttypes/{number}` **Required rights** Authorized user must have `PaymentTypeDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ---------------------------------------- | ---- | --------------------------- | | number\* | int | Unique payment type number. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "number": 1, "category": "Cash", "isActive": true, "description": "Hotovosť", "isChangeable": true, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Plus This page provides a description of the available API routes for managing products. [`PLU`](/data-models#plu) is common abbreviation for goods or services, sold via cash register system. Each PLU can be uniquely identified by its `id` or a combination of the `stockName` and `code` properties. There are several PLU [types](/data-models#plutype) defined in PORTOS system: 1. **Stock item**: This refers to a product that can be physically held in stock. Information regarding stock quantity can be linked to PLUs of the stock item type, using `stockQuantity` property. When customers purchase items of this type, the corresponding stock quantities are updated accordingly. 2. **Recipe**: A recipe PLU represents a product that is a combination of other stock items and/or recipes. When a single unit of a recipe is sold, one or more products of the stock item type are deducted from the stock, based on `receipt` collection. However, no information related to stock quantity is associated with this particular type of PLU. 3. **Service**: This type of PLU represents a product that lacks a physical form. Services, unlike tangible goods, are intangible offerings. They are provided to customers without any physical representation or inventory involvement. 4. **Container**: A container (cover) that can be the subject of a deposit and can be repurchased by a trader. This is an material product that has physical representation and associated stock quantity and can be processed in stock takings. Container PLU must be associated with VAT that represents non-taxable items. Stock items, recipes, services and containers can be accessed through the PLU API routes listed below. ## API methods ## Get PLUs `GET` `http://{server-address}/plus` Returns all roles that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). To retrieve PLUs referenced by receipt as well, specify `Receipt.Plu` value in `$include` query parameter (e.g. `GET {server_address}/plus?$include=Receipt.Plu`). #### Query Parameters | Name | Type | Description | | ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Supports NData syntax. | | articleCategoryLabel | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | code | int | Supports NData syntax. | | color | string | Supports NData syntax. | | isActive | bool | Supports NData syntax. | | isDiscountAllowed | bool | Supports NData syntax. | | isPriceFixed | bool | Supports NData syntax. | | courseNumber | int | Supports NData syntax. | | unit | string | Supports NData syntax. | | type | PluType | Supports NData syntax. | | stockName | string | Supports NData syntax. | | name | string | Supports NData syntax. | | isSplittable | bool | Supports NData syntax. | | stockQuantityAmount | decimal | Supports NData syntax. | | search | string | Provided parameter will perform partial, case insensitive search across name, code and codes properties. | | vatCategory | int | Supports NData syntax. | | isStockQuantitySufficient | bool | If set true, only PLUs with stockQuantity equal or above respective minStockQuantity will be returned. If set to false, only PLUs with stockQuantity less than minStockQuantity will be returned. | | receiptItemPluCode | int | Only PLUs that contains PLU with specified code in receipt collection will match the query. Supports NData syntax. | | receiptItemPluStockName | string | Only PLUs that contains PLU with specified stock name in receipt collection will match the query. Supports NData syntax. | | $include | string | If `Receipt.Plu` is specified as value of query parameter, all [`PluReceiptItem`](/data-models#plureceiptitem)s will contain referenced [`Plu`](/data-models#plu) in `plu` property. See example responses. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "receipt": [ { "pluId": { "code": 1, "stockName": "S11" }, "quantity": { "amount": 3.0, "unit": "ks" } }, { "pluId": { "code": 2, "stockName": "S11" }, "quantity": { "amount": 0.2, "unit": "kg" } } ], "articleCategoryLabel": "RAN", "courseNumber": null, "codes": [], "code": 411, "color": null, "description": null, "customerDescription": null, "id": "64d9e9fac869b340658c98cc", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham & Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "modifiers": [ { "id": "657b20bbde0bfde5af0f59dd" } ], "retailPriceIncludingVat": { "amount": 7.9, "currencyLabel": "EUR" }, "stockName": "S01", "stockQuantity": null, "stockValue": null, "lastPurchasePrice": null, "type": "Recipe", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 }, { "receipt": null, "articleCategoryLabel": "OTH", "courseNumber": null, "codes": [], "code": 1, "color": null, "description": null, "customerDescription": null, "id": "64d9e99cc869b340658c98ca", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "modifiers": null, "retailPriceIncludingVat": { "amount": 0.5, "currencyLabel": "EUR" }, "stockName": "S11", "stockQuantity": { "amount": 10.0, "unit": "ks" }, "stockValue": { "amount": 20.0, "currencyLabel": "EUR" }, "lastPurchasePrice": { "amount": 2.0, "currencyLabel": "EUR" }, "type": "StockItem", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 2 }, { "receipt": null, "articleCategoryLabel": "OTH", "courseNumber": null, "codes": [], "code": 2, "color": null, "description": null, "customerDescription": null, "id": "64d9e9c6c869b340658c98cb", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "modifiers": null, "retailPriceIncludingVat": { "amount": 32.0, "currencyLabel": "EUR" }, "stockName": "S11", "stockQuantity": { "amount": 0.0, "unit": "kg" }, "stockValue": { "amount": 0.0, "currencyLabel": "EUR" }, "lastPurchasePrice": null, "type": "StockItem", "unit": "kg", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 } ], "count": 3, "totalCount": 3 } ``` {% endtab %} {% tab title="200: OK Response using $include=Receipt.Plu query parameter" %} ```json { "items": [ { "receipt": [ { "plu": { "receipt": null, "articleCategoryLabel": "OTH", "courseNumber": null, "codes": [], "code": 1, "color": null, "description": null, "customerDescription": null, "id": "64d9e99cc869b340658c98ca", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "retailPrice": { "amount": 0.5, "currencyLabel": "EUR" }, "stockName": "S11", "stockQuantity": { "amount": 10.0, "unit": "ks" }, "stockValue": { "amount": 20.0, "currencyLabel": "EUR" }, "lastPurchasePrice": { "amount": 2.0, "currencyLabel": "EUR" }, "type": "StockItem", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 }, "pluId": { "code": 1, "stockName": "S11" }, "quantity": { "amount": 3.0, "unit": "ks" } }, { "plu": { "receipt": null, "articleCategoryLabel": "OTH", "courseNumber": null, "codes": [], "code": 2, "color": null, "description": null, "customerDescription": null, "id": "64d9e9c6c869b340658c98cb", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "retailPrice": { "amount": 32.0, "currencyLabel": "EUR" }, "stockName": "S11", "stockQuantity": { "amount": 0.0, "unit": "kg" }, "stockValue": { "amount": 0.0, "currencyLabel": "EUR" }, "lastPurchasePrice": null, "type": "StockItem", "unit": "kg", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 }, "pluId": { "code": 2, "stockName": "S11" }, "quantity": { "amount": 0.2, "unit": "kg" } } ], "articleCategoryLabel": "RAN", "courseNumber": null, "codes": [], "code": 411, "color": null, "description": null, "customerDescription": null, "id": "64d9e9fac869b340658c98cc", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham & Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "retailPrice": { "amount": 7.9, "currencyLabel": "EUR" }, "stockName": "S01", "stockQuantity": null, "stockValue": null, "lastPurchasePrice": null, "type": "Recipe", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 }, { "receipt": null, "articleCategoryLabel": "OTH", "courseNumber": null, "codes": [], "code": 1, "color": null, "description": null, "customerDescription": null, "id": "64d9e99cc869b340658c98ca", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "retailPrice": { "amount": 0.5, "currencyLabel": "EUR" }, "stockName": "S11", "stockQuantity": { "amount": 10.0, "unit": "ks" }, "stockValue": { "amount": 20.0, "currencyLabel": "EUR" }, "lastPurchasePrice": { "amount": 2.0, "currencyLabel": "EUR" }, "type": "StockItem", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 }, { "receipt": null, "articleCategoryLabel": "OTH", "courseNumber": null, "codes": [], "code": 2, "color": null, "description": null, "customerDescription": null, "id": "64d9e9c6c869b340658c98cb", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "retailPrice": { "amount": 32.0, "currencyLabel": "EUR" }, "stockName": "S11", "stockQuantity": { "amount": 0.0, "unit": "kg" }, "stockValue": { "amount": 0.0, "currencyLabel": "EUR" }, "lastPurchasePrice": null, "type": "StockItem", "unit": "kg", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 } ], "count": 3, "totalCount": 3 }// Some code ``` {% endtab %} {% endtabs %} ## Get PLU `GET` `http://{server-address}/plus/{id}` Result is of type [Plu](/data-models#plu). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ---------------------- | | id\* | string | Unique PLU identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found" %} ```javascript { "receipt": [ { "pluId": { "code": 1, "stockName": "S11" }, "quantity": { "amount": 3.0, "unit": "ks" } }, { "pluId": { "code": 2, "stockName": "S11" }, "quantity": { "amount": 0.2, "unit": "kg" } } ], "articleCategoryLabel": "RAN", "courseNumber": null, "codes": [], "code": 411, "color": null, "description": null, "customerDescription": null, "id": "64d9e9fac869b340658c98cc", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham & Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "modifiers": null, "retailPriceIncludingVat": { "amount": 7.9, "currencyLabel": "EUR" }, "stockName": "S01", "stockQuantity": null, "stockValue": null, "lastPurchasePrice": null, "type": "Recipe", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Resource is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create PLU `POST` `http://{server-address}plus` Creates new PLU. Result is of type [Plu](/data-models#plu). **Required rights** Authorized user must have `PluCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ---- | ------------------- | | (body)\* | Plu | PLU model to create | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "receipt": [ { "pluId": { "code": 1, "stockName": "S11" }, "quantity": { "amount": 3.0, "unit": "ks" } }, { "pluId": { "code": 2, "stockName": "S11" }, "quantity": { "amount": 0.2, "unit": "kg" } } ], "articleCategoryLabel": "RAN", "courseNumber": null, "codes": [], "code": 411, "color": null, "description": null, "customerDescription": null, "id": "64d9e9fac869b340658c98cc", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham & Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "modifiers": null, "retailPriceIncludingVat": { "amount": 7.9, "currencyLabel": "EUR" }, "stockName": "S01", "stockQuantity": null, "stockValue": null, "lastPurchasePrice": null, "type": "Recipe", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update PLU `PUT` `http://{server-address}/plus/{id}` Updates existing or creates new PLU. Result is of type [Plu](/data-models#plu). **Required rights** Authorized user must have assigned `PluCreate` or `PluUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ---------------------- | | id\* | string | Unique PLU identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ---- | -------------------------- | | (body)\* | Plu | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "receipt": [ { "pluId": { "code": 1, "stockName": "S11" }, "quantity": { "amount": 3.0, "unit": "ks" } }, { "pluId": { "code": 2, "stockName": "S11" }, "quantity": { "amount": 0.2, "unit": "kg" } } ], "articleCategoryLabel": "RAN", "courseNumber": null, "codes": [], "code": 411, "color": null, "description": null, "customerDescription": null, "id": "64d9e9fac869b340658c98cc", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham & Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "modifiers": null, "retailPriceIncludingVat": { "amount": 7.9, "currencyLabel": "EUR" }, "stockName": "S01", "stockQuantity": null, "stockValue": null, "lastPurchasePrice": null, "type": "Recipe", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Delete PLU `DELETE` `http://{server-address}/plus/{id}` **Required rights** Authorized user must have `PluDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ---------------------- | | id\* | string | Unique PLU identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "receipt": [ { "pluId": { "code": 1, "stockName": "S11" }, "quantity": { "amount": 3.0, "unit": "ks" } }, { "pluId": { "code": 2, "stockName": "S11" }, "quantity": { "amount": 0.2, "unit": "kg" } } ], "articleCategoryLabel": "RAN", "courseNumber": null, "codes": [], "code": 411, "color": null, "description": null, "customerDescription": null, "id": "64d9e9fac869b340658c98cc", "isActive": true, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": false, "minStockQuantity": null, "name": "Ham & Eggs", "orderEndpointNames": [], "priceHistory": [], "images": null, "ordering": null, "purchaseTypes": null, "modifiers": null, "retailPriceIncludingVat": { "amount": 7.9, "currencyLabel": "EUR" }, "stockName": "S01", "stockQuantity": null, "stockValue": null, "lastPurchasePrice": null, "type": "Recipe", "unit": "ks", "vatCategory": 1, "packaging": null, "specialRegulation": null, "isCashbackAllowed": false, "isFavorite": false, "sortHint": null, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Roles This page provides a description of the available API routes for managing roles. The PORTOS system has a predefined list of [user rights](/user-rights). Role allows to combine multiple user rights. When assigning rights to the user, roles are used. The role is represented by [`Role`](/data-models#role) class. Roles can be freely managed using API routes described in this section. For instance, a user possessing the "sale" role would be granted rights such as `ticketCreate`, `ticketUpdate`, and `ticketClose`. Roles can be used to group user rights based on areas of work or represent specific job positions like "cashier," "waiter," or "manager." During product installation, the default roles setup is established, and it follows a more detailed approach, allowing precise role management, such as "sale", "stats", "storno," etc. ## API methods ## Get roles `GET` `http://{server-address}/roles` Returns all roles that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------ | | name | string | Supports NData syntax. | | label | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "sessionId": "soZIt6uj62fzs8ep4UvnNSxRXFryUiq3", "identity": { "userName": "999", "deviceName": "P01", "envName": "CashRegister", "authenticationType": "Bearer" }, "startedAt": "2023-08-04T11:19:38.015Z", "expiresAt": "2023-08-04T23:19:38.015Z", "lastAccessAt": "2023-08-04T11:19:39.98Z", "_v": 2 }, { "sessionId": "Hq6563mjODIOwNa87Cgi295uNPlKeOqA", "identity": { "userName": "999", "deviceName": "BackOffice", "envName": "BackOffice", "authenticationType": "Bearer" }, "startedAt": "2023-08-04T21:21:07.66Z", "expiresAt": "2023-08-05T09:21:07.66Z", "lastAccessAt": "2023-08-04T21:21:11.578Z", "_v": 4 } ], "count": 2, "totalCount": 2 } ``` {% endtab %} {% endtabs %} ## Get session `GET` `http://{server-address}/sessions/{id}` Result is of type [Session](/data-models#session). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | -------------------------- | | id\* | string | Unique session identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "sessionId": "Hq6563mjODIOwNa87Cgi295uNPlKeOqA", "identity": { "userName": "999", "deviceName": "BackOffice", "envName": "BackOffice", "authenticationType": "Bearer" }, "startedAt": "2023-08-04T21:21:07.66Z", "expiresAt": "2023-08-05T09:21:07.66Z", "lastAccessAt": "2023-08-04T21:21:11.578Z", "_v": 7 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Delete session `DELETE` `http://{server-address}/sessions/{id}` Result is of type [Session](/data-models#session). **Required rights** No user rights are required to perform this method. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | -------------------------- | | id\* | string | Unique session identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="204: No Content Successfully deleted." %} ```javascript { "sessionId": "Hq6563mjODIOwNa87Cgi295uNPlKeOqA", "identity": { "userName": "999", "deviceName": "BackOffice", "envName": "BackOffice", "authenticationType": "Bearer" }, "startedAt": "2023-08-04T21:21:07.66Z", "expiresAt": "2023-08-05T09:21:07.66Z", "lastAccessAt": "2023-08-04T21:21:11.578Z", "_v": 7 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Settings This page provides a description of the available API routes for managing settings. The API offers a range of modules and extensions that require configuration. In order to faciliate the process of module configuration, the API provides methods for accessing and managing stored configurations. These configurations are represented by a [`Settings`](/api-reference/settings) class. Every module has its unique identifier, which is used as key when accessing given configuration section. ## API methods ## Get settings `GET` `http://{server-address}/settings` Returns all stored settings. Result is of type `Dictionary`. The dictionary keys represents settings section keys. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "Portos.Features.Qerko": { "IsEnabled": true, "ApiKey": "aaaa-bbbb-cccc-dddd-eeee-ffff", "Environment": "development", "StockName": "Qerko", "FiscalName": "eKasa", "TicketForm": "Print", "PaymentTypeNumber": 2, "AllowPartialPayment": true, "IsTipAllowed": true, "IsOrderToTicketEnabled": true, "IsOrderToTableEnabled": true, "IsTakeAwayOrderEnabled": true, "IsOrderConfirmationPrintingEnabled": true, "IsPaymentConfirmationPrintingEnabled": true, "IsNettoTipOnPaymentConfirmationEnabled": false, "UploadMenuOnStart": true, "OutOfStockMode": "belowMinimalStockQuantity", "TipVatCategory": 1, "DiscountVatCategory": 1 }, "Portos.Features.Camarero": { "IsEnabled": false, "InputDirectoryPath": "C:/POS/", "UnprocessableFilesDirectoryPath": "C:/POS/FAILED/", "FileReadMaxRetryCount": 3, "FileReadRetryDelayMs": 300, "FileExtension": ".pda", "QuantityScale": 2, "UnitPriceScale": 2, "DefaultStockName": "S02", "DefaultFiscalName": null, "DefaultVatCategory": 1, "DefaultUnit": "ks", "DefaultPurchaseType": "WalkIn", "RoundingTreshold": 0.05, "SkipOrdersProcessing": true, "ProcessOrders": false }, "Portos.Features.OrderManagement": { "LastOrderNumber": 1 } } ``` {% endtab %} {% endtabs %} ## Get settings section `GET` `http://{server-address}/settings/{key}` Result is of type [Settings](/data-models#settings). #### Path Parameters | Name | Type | Description | | ------------------------------------- | ------ | -------------------------------- | | key\* | string | The settings section identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "LastOrderNumber": 1 } ``` {% endtab %} {% tab title="404: Not Found Settings section is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create or update settings section `PUT` `http://{server-address}/settings/{key}` Updates existing or creates new settings section. The result of this operation is of type [Settings](/data-models#settings). **Required rights** No user rights are required. #### Path Parameters | Name | Type | Description | | ------------------------------------- | ------ | -------------------------------- | | key\* | string | The settings section identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | ------------------------- | | (body)\* | Settings | Settings object to store. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "LastOrderNumber": 1 } ``` {% endtab %} {% endtabs %} ## Partially update settings section `PATCH` `http://{server-address}/settings` This method updates only a subset of the settings section. Any properties that are not present in the request body will remain unchanged. The result of this operation is of type [Settings](/data-models#settings). **Required rights** No user rights are required. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | -------- | --------------------------------- | | (body)\* | Settings | Partial settings object to store. | {% tabs %} {% tab title="200: OK Successfuly updated." %} ```javascript { "LastOrderNumber": 1 } ``` {% endtab %} {% endtabs %} ## Delete settings section `DELETE` `http://{server-address}/settings/{key}` **Required rights** No user rights are required. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | -------------------------------- | | name\* | string | The settings section identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "LastOrderNumber": 1 } ``` {% endtab %} {% endtabs %} # Stock takings This page provides a description of the available API routes for managing stock takings. Stock taking (represented by [`StockTaking`](/data-models#stocktaking) class) is a method to adjust stock quantities for various stock items (`Plu` of type `StockItem`). These adjustments can be made multiple times until the stock taking is marked as *closed* by providing values for the `ClosedBy` and `ClosedAt` fields. Once a stock taking is closed, it becomes read-only and cannot be reopened. To close a stock taking, `ActualQuantity` must be provided for each item element (represented by [`StockTakingItem`](/data-models#stocktakingitem) class). After a stock taking is closed, the API server automatically generates a new stock transfer (represented by [`StockTransfer`](/data-models#stocktransfer) class) with the type `correction`. This stock transfer is used to execute the necessary stock quantity corrections for the items involved in the stock taking process. ## API methods ## Get stock takings `GET` `http://{server-address}/stocktakings` Returns all stocks that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | id | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | createdAt | DateTime | Supports NData syntax. | | createdByUserName | string | Only stock takings containing item with matching StockTaking.CreatedBy.UserName property are returned. Supports NData syntax. | | closedAt | DateTime | Supports NData syntax. | | closedByUserName | string | Only stock takings containing item with matching StockTaking.ClosedBy.UserName property are returned. Supports NData syntax. | | currencyLabel | string | Supports NData syntax. | | itemPluStockName | string | Only stock takings containing item with matching StockTakingItem.Plu.StockName property are returned. Supports NData syntax. | | itemPluCode | int | Only stock takings containing item with matching StockTakingItem.Plu.Code property are returned. Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "64cfa2153a6484c761208b8c", "createdAt": "2023-08-06T13:37:25.728Z", "closedAt": null, "createdBy": { "name": "Majiteľ", "userName": "999", "featureName": null }, "closedBy": null, "currencyLabel": "EUR", "items": [ { "expectedQuantity": { "amount": 15.0, "unit": "ks" }, "actualQuantity": { "amount": 12.0, "unit": "ks" }, "plu": { "name": "Coca Cola 0,33l", "code": 5, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 6.0, "unit": "ks" }, "actualQuantity": { "amount": 5.0, "unit": "ks" }, "plu": { "name": "Fanta 0.33l", "code": 6, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 11.0, "unit": "ks" }, "actualQuantity": null, "plu": { "name": "Sprite 0.33l", "code": 7, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } } ], "_v": 1 } ], "count": 1, "totalCount": 1 } ``` {% endtab %} {% endtabs %} ## Get stock taking `GET` `http://{server-address}/stocktakings/{id}` Result is of type [StockTaking](/data-models#stocktaking). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "id": "64cfa2153a6484c761208b8c", "createdAt": "2023-08-06T13:37:25.728Z", "closedAt": null, "createdBy": { "name": "Majiteľ", "userName": "999", "featureName": null }, "closedBy": null, "currencyLabel": "EUR", "items": [ { "expectedQuantity": { "amount": 15.0, "unit": "ks" }, "actualQuantity": { "amount": 12.0, "unit": "ks" }, "plu": { "name": "Coca Cola 0,33l", "code": 5, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 6.0, "unit": "ks" }, "actualQuantity": { "amount": 5.0, "unit": "ks" }, "plu": { "name": "Fanta 0.33l", "code": 6, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 11.0, "unit": "ks" }, "actualQuantity": null, "plu": { "name": "Sprite 0.33l", "code": 7, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Resource not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create stock taking `POST` `http://{server-address}/stocktakings` Creates new stock taking. Result is of type [StockTaking](/data-models#stocktaking). **Required rights** Authorized user must have `StockTakingCreate` [right ](/user-rights)assigned. If stock taking is marked as closed, `StockTakingClose` [right ](/user-rights)is required as well. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ----------- | --------------- | | (body)\* | StockTaking | Model to create | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "id": "64cfa2153a6484c761208b8c", "createdAt": "2023-08-06T13:37:25.728Z", "closedAt": null, "createdBy": { "name": "Majiteľ", "userName": "999", "featureName": null }, "closedBy": null, "currencyLabel": "EUR", "items": [ { "expectedQuantity": { "amount": 15.0, "unit": "ks" }, "actualQuantity": { "amount": 12.0, "unit": "ks" }, "plu": { "name": "Coca Cola 0,33l", "code": 5, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 6.0, "unit": "ks" }, "actualQuantity": { "amount": 5.0, "unit": "ks" }, "plu": { "name": "Fanta 0.33l", "code": 6, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 11.0, "unit": "ks" }, "actualQuantity": null, "plu": { "name": "Sprite 0.33l", "code": 7, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } } ], "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update stock taking `PUT` `http://{server-address}/stocktakings/{id}` Updates existing or creates new stock taking. Result is of type [StockTaking](/data-models#stocktaking). **Required rights** Authorized user must have assigned `StockTakingCreate` or `StockTakingUpdate` [right](/user-rights). If stock taking is marked as closed, `StockTakingClose` [right ](/user-rights)is required as well. Only stock takings not marked as closed can be updated. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ----------- | -------------------------- | | (body)\* | StockTaking | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "id": "64cfa2153a6484c761208b8c", "createdAt": "2023-08-06T13:37:25.728Z", "closedAt": null, "createdBy": { "name": "Majiteľ", "userName": "999", "featureName": null }, "closedBy": null, "currencyLabel": "EUR", "items": [ { "expectedQuantity": { "amount": 15.0, "unit": "ks" }, "actualQuantity": { "amount": 12.0, "unit": "ks" }, "plu": { "name": "Coca Cola 0,33l", "code": 5, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 6.0, "unit": "ks" }, "actualQuantity": { "amount": 5.0, "unit": "ks" }, "plu": { "name": "Fanta 0.33l", "code": 6, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 11.0, "unit": "ks" }, "actualQuantity": null, "plu": { "name": "Sprite 0.33l", "code": 7, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } } ], "_v": 1 } ``` {% endtab %} {% endtabs %} ## Delete stock taking `DELETE` `http://{server-address}/stocktakings/{id}` **Required rights** Authorized user must have `StockTakingDelete` [right ](/user-rights)assigned. Only stock takings not marked as closed can be deleted. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "id": "64cfa2153a6484c761208b8c", "createdAt": "2023-08-06T13:37:25.728Z", "closedAt": null, "createdBy": { "name": "Majiteľ", "userName": "999", "featureName": null }, "closedBy": null, "currencyLabel": "EUR", "items": [ { "expectedQuantity": { "amount": 15.0, "unit": "ks" }, "actualQuantity": { "amount": 12.0, "unit": "ks" }, "plu": { "name": "Coca Cola 0,33l", "code": 5, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 6.0, "unit": "ks" }, "actualQuantity": { "amount": 5.0, "unit": "ks" }, "plu": { "name": "Fanta 0.33l", "code": 6, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } }, { "expectedQuantity": { "amount": 11.0, "unit": "ks" }, "actualQuantity": null, "plu": { "name": "Sprite 0.33l", "code": 7, "codes": [], "stockName": "S01", "articleCategoryLabel": "DRI", "vat": { "category": 1, "rate": 20.0 }, "unitPurchasePrice": { "amount": 0.0, "currencyLabel": "EUR" }, "unitRetailPrice": { "amount": 3.491667, "currencyLabel": "EUR" } } } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Stock transfer numbering This page provides a description of the available API routes for managing stock transfer numberings. When [stock transfer](/data-models#stocktransfer) is created, the `documentNumber` field is generated by server, based on [stock transfer numbering](/data-models#stocktransfernumbering) settings. API methods listed below provides way to modify numbering settings. ## API methods ## Get stock transfer numberings `GET` `http://{server-address}/stocktransfernumberings` Returns all stock transfer numberings that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | | id | string | Supports NData syntax. | | isActive | bool | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | type | StockTransferType | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "59919dc4c5960398d3774162", "isActive": true, "type": "Outcome", "format": "V-{yyyy}{MM}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2023-01-01T00:00:00Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Month", "amount": 1 }, "currentNumber": 1 } ], "_v": 1 }, { "id": "59919dcac5960398d3774163", "isActive": true, "type": "Transfer", "format": "T-{yyyy}{MM}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2023-01-01T00:00:00Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Month", "amount": 1 }, "currentNumber": 1 } ], "_v": 1 }, { "id": "59919e02c5960398d3774165", "isActive": true, "type": "Correction", "format": "K-{yyyy}{MM}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2023-01-01T00:00:00Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Month", "amount": 1 }, "currentNumber": 1 } ], "_v": 1 }, { "id": "59919dd9c5960398d3774164", "isActive": true, "type": "Invoice", "format": "FA-{yyyy}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2022-01-01T00:00:00Z", "startAt": "2022-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 12 }, { "isActive": true, "createdAt": "2023-01-16T09:01:55.711Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 8 } ], "_v": 1 } ], "count": 4, "totalCount": 4 } ``` {% endtab %} {% endtabs %} ## Get stock transfer numbering `GET` `http://{server-address}/stocktransfernumberings/{id}` Result is of type [StockTransferNumbering](/data-models#stocktransfernumbering). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "id": "59919dd9c5960398d3774164", "isActive": true, "type": "Invoice", "format": "FA-{yyyy}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2022-01-01T00:00:00Z", "startAt": "2022-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 12 }, { "isActive": true, "createdAt": "2023-01-16T09:01:55.711Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 8 } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Resource is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create stock transfer numbering `POST` `http://{server-address}/stocktransfernumberings` Creates new stock transfer numbering. Result is of type [StockTransferNumbering](/data-models#stocktransfernumbering). **Required rights** Authorized user must have `StockTransferNumberingCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ---------------------- | --------------- | | (body)\* | StockTransferNumbering | Model to create | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "id": "59919dd9c5960398d3774164", "isActive": true, "type": "Invoice", "format": "FA-{yyyy}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2022-01-01T00:00:00Z", "startAt": "2022-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 12 }, { "isActive": true, "createdAt": "2023-01-16T09:01:55.711Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 8 } ], "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update stock transfer numbering `PUT` `http://{server-address}/stocktransfernumberings/{id}` Updates existing or creates new stock transfer numbering. Result is of type [StockTransferNumbering](/data-models#stocktransfernumbering). **Required rights** Authorized user must have assigned `StockTransferNumberingCreate` or `StockTransferNumberingUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ---------------------- | -------------------------- | | (body)\* | StockTransferNumbering | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "id": "59919dd9c5960398d3774164", "isActive": true, "type": "Invoice", "format": "FA-{yyyy}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2022-01-01T00:00:00Z", "startAt": "2022-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 12 }, { "isActive": true, "createdAt": "2023-01-16T09:01:55.711Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 8 } ], "_v": 1 } ``` {% endtab %} {% endtabs %} ## Delete stock transfer numbering `DELETE` `http://{server-address}/stocktransfernumberings/{id}` **Required rights** Authorized user must have `StockTransferNumberingDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------ | | id\* | string | Unique identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "id": "59919dd9c5960398d3774164", "isActive": true, "type": "Invoice", "format": "FA-{yyyy}{i4}", "repeat": true, "numberings": [ { "isActive": true, "createdAt": "2022-01-01T00:00:00Z", "startAt": "2022-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 12 }, { "isActive": true, "createdAt": "2023-01-16T09:01:55.711Z", "startAt": "2023-01-01T00:00:00Z", "period": { "unit": "Year", "amount": 1 }, "currentNumber": 8 } ], "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Stock transfers This page provides a description of the available API routes for managing stock transfers. [Stock transfer](/data-models#stocktransfer) refers to an operation that alters the quantity of products within storage. Various types of stock transfers are defined, each tailored to a specific purpose: increasing, decreasing, or fixing inaccuracies in stock quantity. 1. **Income**: This category signifies the purchase of goods from suppliers, leading to an increase in the stock quantity of the purchased items. 2. **Outcome**: Applies when goods are withdrawn from storage due to reasons such as expiration, etc. 3. **Transfer**: Relocation of goods from one stock location to another within the inventory. 4. **Sale**: Comparable to an "outcome," the system generates this transfer type automatically once a ticket is closed. Each sale stock transfer is associated with a single corresponding ticket. 5. **Invoice**: Similar to the "outcome" type, the "invoice" transfer may be used when goods are not directly sold through a cash register. 6. **Correction**: Generated automatically by system after finalizing of stock-taking process (closing the [stock taking](/api-reference/stock-takings)). Its role is to fix inaccuracies in stock quantities that were not matched during the stock-taking phase. May contain both positive and negative stock quantity changes. ## API methods ## Get stock transfers `GET` `http://{server-address}/stocktransfers` Returns all stock transfers that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ----------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | | type | StockTransferType | Supports NData syntax. | | id | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | specificSymbol | string | Supports NData syntax. | | constantSymbol | string | Supports NData syntax. | | variableSymbol | string | Supports NData syntax. | | deliveryDate | DateTime | Supports NData syntax. | | documentDate | DateTime | Supports NData syntax. | | documentNumber | string | Supports NData syntax. | | dueDate | DateTime | Supports NData syntax. | | closedByUserName | string | Filtering based on `closedBy.userName` property. Supports NData syntax. | | closedAt | DateTime | Supports NData syntax. | | createdByUserName | string | Filtering based on `createdBy.userName` property. Supports NData syntax. | | partnerCRN | string | Filtering based on `partner.crn` property. Supports NData syntax. | | companyCRN | string | Filtering based on `company.crn` property. Supports NData syntax. | | itemSourceOrDestinationPluCode | int | Filtering based on `sourcePlu.code` and `destinationPlu.code` properties in `items` collection. Supports NData syntax. | | currencyLabel | string | Supports NData syntax. | | discountRate | decimal | Supports NData syntax. | | paymentType | string | Supports NData syntax. | | deliveryType | string | Supports NData syntax. | | itemDestinationPluStockName | string | Filtering based on `destinationPlu.stockName` property in `items` collection. Supports NData syntax. | | itemSourcePluCode | int | Filtering based on `sourcePlu.code` property in `items` collection. Supports NData syntax. | | itemSourcePluStockName | string | Filtering based on `sourcePlu.stockName` property in `items` collection. Supports NData syntax. | | itemSourceOrDestinationPluStockName | string | Filtering based on `sourcePlu.stockName` and `destinationPlu.stockName` properties in `items` collection. Supports NData syntax. | | itemDestinationPluCode | int | Filtering based on `destinationPlu.code` property in `items` collection. Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript ``` {% endtab %} {% endtabs %} ## Get stock transfer `GET` `http://{server-address}/stocktransfers/{id}` Result is of type [StockTransfer](/data-models#stocktransfer). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | -------------------------- | | id\* | string | Stock transfer identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript ``` {% endtab %} {% tab title="404: Not Found Resource is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create stock transfer `POST` `http://{server-address}/stocktransfers` Creates new stock transfer. Result is of type [StockTransfer](/data-models#stocktransfer). **Required rights** Authorized user must have `StockTransferCreate` [right ](/user-rights)assigned. If stock transfer is marked as closed, additional `StockTransferClose` [right ](/user-rights)is required. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------- | --------------- | | (body)\* | StockTransfer | Model to create | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript ``` {% endtab %} {% endtabs %} ## Create or update stock transfer `PUT` `http://{server-address}/stocktransfers/{id}` Updates existing or creates new stock transfer. Result is of type [StockTransfer](/data-models#stocktransfer). Stock transfer marked as closed cannot be updated. **Required rights** Authorized user must have assigned `StockTransferCreate` or `StockTransferUpdate` [right](/user-rights). If stock transfer is created by another user, additional `StockTransferUpdateAny` [right ](/user-rights)is required. If stock transfer is marked as closed, additional `StockTransferClose` [right ](/user-rights)is required. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | -------------------------- | | id\* | string | Stock transfer identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------- | -------------------------- | | (body)\* | StockTransfer | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript ``` {% endtab %} {% endtabs %} ## Delete stock transfer `DELETE` `http://{server-address}/stocktransfers/{id}` **Required rights** Authorized user must have `StockTransferDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | -------------------------- | | id\* | string | Stock transfer identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Stocks This page provides a description of the available API routes for managing stocks. Each Product (represented by [`Plu`](/data-models#plu) model) is associated with stock through its `StockName` property. Stocks are represented by [`Stock`](/data-models#stock) class and uniquely identified by their names (`stock.Name` property). A stock can group multiple products (e.g. stock called "Menu" that contains products that can be listed in cash register and stock called "Material" that contains raw materials and other resources in kitchen). Each product has a unique code (`plu.Code` property) within its respective stock. ## API methods ## Get stocks `GET` `http://{server-address}/stocks` Returns all stocks that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------ | | name | string | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

If set to true, response will not contain items collection. Use to get resource count, not the resources themselves.

| #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "635f70e1fa3dab15784a0b45", "externalId": null, "state": "Closed", "type": "CashRegister", "name": "7", "openDate": "2022-10-31T06:53:20.76Z", "issueDate": null, "closeDate": "2022-10-31T07:05:43Z", "closeInfo": { "eKasa": null, "dailySalesReportNumber": 123, "number": 3, "fiscalMemorySerialNumber": "347...005", "fiscalName": "eKasa", "deviceName": "P01" }, "purchaseType": "WalkIn", "location": { "zoneName": "Bar", "tableName": "B7" }, "customer": { "id": null, "externalId": null, "cardSerialNumber": "customer-card-serial-number", "firstName": null, "lastName": null, "fullName": "John Doe", "gender": null, "birthDate": null, "address": null, "deliveryAddress": null, "isCompany": false, "company": null, "phone": null, "email": null, "creditRate": null, "meta": {} }, "originDeviceName": "P01", "employee": { "name": "Mr. Waiter", "userName": "1", "featureName": null }, "items": [ { "id": 1, "externalId": null, "type": "Positive", "plu": { "name": "Cappucino", "description": null, "stockName": "S01", "code": 9, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.083333, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": [ { "id": 95674534, "externalId": null, "type": 0, "plu": { "name": "Extra milk", "description": null, "stockName": "S01", "code": 3001, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": "5" }, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": 2, "specialRegulation": null, "isCashbackAllowed": true }, "quantity": { "amount": 1.0, "unit": "ks" }, "unitPrice": { "amount": 0.0, "currencyLabel": "EUR" }, "discountRate": 0.0, "comment": null, "voucherNumber": null, "isQuantityFixed": false, "modifier": { "id": "66681cbe9f5a50cd4e9a6b75", "optionId": "66681cbe9f5a50cd4e9a6b75" } } ] }, { "id": 2, "externalId": null, "type": "Positive", "plu": { "name": "Espresso Doppio", "description": null, "stockName": "S01", "code": 7, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.166667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": [ { "id": 95674367, "externalId": null, "type": 0, "plu": { "name": "Extra milk", "description": null, "stockName": "S01", "code": 3001, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": "5" }, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": 2, "specialRegulation": null, "isCashbackAllowed": true }, "quantity": { "amount": 1.0, "unit": "ks" }, "unitPrice": { "amount": 0.0, "currencyLabel": "EUR" }, "discountRate": 0.0, "comment": null, "voucherNumber": null, "isQuantityFixed": false, "modifier": { "id": "66681cbe9f5a50cd4e9a6b75", "optionId": "66681cbe9f5a50cd4e9a6b75" } } ] }, { "id": 3, "externalId": null, "type": "Positive", "plu": { "name": "Espresso", "description": null, "stockName": "S01", "code": 1, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 1.416667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 4, "externalId": null, "type": "Positive", "plu": { "name": "Mlieko", "description": null, "stockName": "S01", "code": 49, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 0.25, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null } ], "payments": [ { "paymentType": { "number": 2, "description": "Kreditná karta", "isChangeable": false, "category": "CreditCard" }, "amount": { "amount": 6.73, "currencyLabel": "EUR", "domesticCurrencyLabel": "EUR", "exchangeRate": 1.0 } } ], "currencyLabel": "EUR", "discountRate": 5.0, "roundingAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceNumber": null, "paragonNumber": null, "isParagon": false, "_v": 2 } ], "count": 1, "totalCount": 258773 } ``` {% endtab %} {% endtabs %} ## Get ticket `GET` `http://{server-address}/tickets/{id}` Result is of type [`Ticket`](#ticket). #### Query Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------------ | | id\* | string | Unique ticket identifier | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Success response. Ticket is found." %} ```javascript { "id": "635f70e1fa3dab15784a0b45", "externalId": null, "state": "Closed", "type": "CashRegister", "name": "7", "openDate": "2022-10-31T06:53:20.76Z", "issueDate": null, "closeDate": "2022-10-31T07:05:43Z", "closeInfo": { "eKasa": null, "dailySalesReportNumber": 123, "number": 3, "fiscalMemorySerialNumber": "347...005", "fiscalName": "eKasa", "deviceName": "P01" }, "purchaseType": "WalkIn", "location": { "zoneName": "Bar", "tableName": "B7" }, "customer": { "id": null, "externalId": null, "cardSerialNumber": "customer-card-serial-number", "firstName": null, "lastName": null, "fullName": "John Doe", "gender": null, "birthDate": null, "address": null, "deliveryAddress": null, "isCompany": false, "company": null, "phone": null, "email": null, "creditRate": null, "meta": {} }, "originDeviceName": "P01", "employee": { "name": "Mr. Waiter", "userName": "1", "featureName": null }, "items": [ { "id": 1, "externalId": null, "type": "Positive", "plu": { "name": "Cappucino", "description": null, "stockName": "S01", "code": 9, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.083333, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": [ { "id": 95674534, "externalId": null, "type": 0, "plu": { "name": "Extra milk", "description": null, "stockName": "S01", "code": 3001, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": "5" }, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": 2, "specialRegulation": null, "isCashbackAllowed": true }, "quantity": { "amount": 1.0, "unit": "ks" }, "unitPrice": { "amount": 0.0, "currencyLabel": "EUR" }, "discountRate": 0.0, "comment": null, "voucherNumber": null, "isQuantityFixed": false, "modifier": { "id": "66681cbe9f5a50cd4e9a6b75", "optionId": "66681cbe9f5a50cd4e9a6b75" } } ] }, { "id": 2, "externalId": null, "type": "Positive", "plu": { "name": "Espresso Doppio", "description": null, "stockName": "S01", "code": 7, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.166667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": [ { "id": 95674367, "externalId": null, "type": 0, "plu": { "name": "Extra milk", "description": null, "stockName": "S01", "code": 3001, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": "5" }, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": 2, "specialRegulation": null, "isCashbackAllowed": true }, "quantity": { "amount": 1.0, "unit": "ks" }, "unitPrice": { "amount": 0.0, "currencyLabel": "EUR" }, "discountRate": 0.0, "comment": null, "voucherNumber": null, "isQuantityFixed": false, "modifier": { "id": "66681cbe9f5a50cd4e9a6b75", "optionId": "66681cbe9f5a50cd4e9a6b75" } } ] }, { "id": 3, "externalId": null, "type": "Positive", "plu": { "name": "Espresso", "description": null, "stockName": "S01", "code": 1, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 1.416667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 4, "externalId": null, "type": "Positive", "plu": { "name": "Mlieko", "description": null, "stockName": "S01", "code": 49, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 0.25, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null } ], "payments": [ { "paymentType": { "number": 2, "description": "Kreditná karta", "isChangeable": false, "category": "CreditCard" }, "amount": { "amount": 6.73, "currencyLabel": "EUR", "domesticCurrencyLabel": "EUR", "exchangeRate": 1.0 } } ], "currencyLabel": "EUR", "discountRate": 5.0, "roundingAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceNumber": null, "paragonNumber": null, "isParagon": false, "_v": 2 } ``` {% endtab %} {% tab title="404: Not Found Ticket with given ID is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create ticket `POST` `http://{server-address}/tickets` Creates new opened ticket. Result is of type [`Ticket`](#ticket). **Required rights** Please see [User rights required for creating and modifying ticket](/api-reference/tickets/ticket-operations-and-user-rights#creating-and-modifying-ticket) section. **Required environments** [Sale environment](/device-environments) required. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | --------------- | | (body)\* | Ticket | Model to create | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "id": "635f70e1fa3dab15784a0b45", "externalId": null, "state": "Closed", "type": "CashRegister", "name": "7", "openDate": "2022-10-31T06:53:20.76Z", "issueDate": null, "closeDate": "2022-10-31T07:05:43Z", "closeInfo": { "eKasa": null, "dailySalesReportNumber": 123, "number": 3, "fiscalMemorySerialNumber": "347...005", "fiscalName": "eKasa", "deviceName": "P01" }, "purchaseType": "WalkIn", "location": { "zoneName": "Bar", "tableName": "B7" }, "customer": { "id": null, "externalId": null, "cardSerialNumber": "customer-card-serial-number", "firstName": null, "lastName": null, "fullName": "John Doe", "gender": null, "birthDate": null, "address": null, "deliveryAddress": null, "isCompany": false, "company": null, "phone": null, "email": null, "creditRate": null, "meta": {} }, "originDeviceName": "P01", "employee": { "name": "Mr. Waiter", "userName": "1", "featureName": null }, "items": [ { "id": 1, "externalId": null, "type": "Positive", "plu": { "name": "Cappucino", "description": null, "stockName": "S01", "code": 9, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.083333, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": [ { "id": 95674534, "externalId": null, "type": 0, "plu": { "name": "Extra milk", "description": null, "stockName": "S01", "code": 3001, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": "5" }, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": 2, "specialRegulation": null, "isCashbackAllowed": true }, "quantity": { "amount": 1.0, "unit": "ks" }, "unitPrice": { "amount": 0.0, "currencyLabel": "EUR" }, "discountRate": 0.0, "comment": null, "voucherNumber": null, "isQuantityFixed": false, "modifier": { "id": "66681cbe9f5a50cd4e9a6b75", "optionId": "66681cbe9f5a50cd4e9a6b75" } } ] }, { "id": 2, "externalId": null, "type": "Positive", "plu": { "name": "Espresso Doppio", "description": null, "stockName": "S01", "code": 7, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.166667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": [ { "id": 95674367, "externalId": null, "type": 0, "plu": { "name": "Extra milk", "description": null, "stockName": "S01", "code": 3001, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": "5" }, "isDiscountAllowed": true, "isPriceFixed": false, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": 2, "specialRegulation": null, "isCashbackAllowed": true }, "quantity": { "amount": 1.0, "unit": "ks" }, "unitPrice": { "amount": 0.0, "currencyLabel": "EUR" }, "discountRate": 0.0, "comment": null, "voucherNumber": null, "isQuantityFixed": false, "modifier": { "id": "66681cbe9f5a50cd4e9a6b75", "optionId": "66681cbe9f5a50cd4e9a6b75" } } ] }, { "id": 3, "externalId": null, "type": "Positive", "plu": { "name": "Espresso", "description": null, "stockName": "S01", "code": 1, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 1.416667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 4, "externalId": null, "type": "Positive", "plu": { "name": "Mlieko", "description": null, "stockName": "S01", "code": 49, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 0.25, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null } ], "payments": [ { "paymentType": { "number": 2, "description": "Kreditná karta", "isChangeable": false, "category": "CreditCard" }, "amount": { "amount": 6.73, "currencyLabel": "EUR", "domesticCurrencyLabel": "EUR", "exchangeRate": 1.0 } } ], "currencyLabel": "EUR", "discountRate": 5.0, "roundingAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceNumber": null, "paragonNumber": null, "isParagon": false, "_v": 2 } ``` {% endtab %} {% endtabs %} ## Create or update ticket `PUT` `http://{server-address}/tickets/{id}` Creates new or updates existing opened ticket. Attempt to update closed ticket will result in HTTP Status 403 (Forbidden). Result is of type [`Ticket`](#ticket). **Required rights** Please see [User rights required for creating and modifying ticket](/api-reference/tickets/ticket-operations-and-user-rights#creating-and-modifying-ticket) section. **Required environments** [Sale environment](/device-environments) required. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------------ | | id\* | string | Unique ticket identifier | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | -------------------------- | | (body)\* | Ticket | Model to create or update. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "id": "635f70e1fa3dab15784a0b45", "externalId": null, "state": "Open", "type": "CashRegister", "name": "7", "openDate": "2022-10-31T06:53:20.76Z", "issueDate": null, "closeDate": null, "closeInfo": null, "purchaseType": "WalkIn", "location": { "zoneName": "Bar", "tableName": "B7" }, "customer": { "id": null, "externalId": null, "cardSerialNumber": "customer-card-serial-number", "firstName": null, "lastName": null, "fullName": "John Doe", "gender": null, "birthDate": null, "address": null, "deliveryAddress": null, "isCompany": false, "company": null, "phone": null, "email": null, "creditRate": null, "meta": {} }, "originDeviceName": "P01", "employee": { "name": "Mr. Waiter", "userName": "1", "featureName": null }, "items": [ { "id": 1, "externalId": null, "type": "Positive", "plu": { "name": "Cappucino", "description": null, "stockName": "S01", "code": 9, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.083333, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 2, "externalId": null, "type": "Positive", "plu": { "name": "Espresso Doppio", "description": null, "stockName": "S01", "code": 7, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.166667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 3, "externalId": null, "type": "Positive", "plu": { "name": "Espresso", "description": null, "stockName": "S01", "code": 1, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 1.416667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 4, "externalId": null, "type": "Positive", "plu": { "name": "Mlieko", "description": null, "stockName": "S01", "code": 49, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 0.25, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null } ], "payments": [], "currencyLabel": "EUR", "discountRate": 5.0, "roundingAmount": null, "invoiceNumber": null, "paragonNumber": null, "isParagon": false, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Batch tickets update `PATCH` `http://{server-address}/tickets` Preforms batch update of one or more [tickets](/data-models#ticket). Collection of affected [tickets](/data-models#ticket) is returned. **Required rights** Please see [User rights required for creating and modifying ticket](/api-reference/tickets/ticket-operations-and-user-rights#creating-and-modifying-ticket) section. **Required environments** [Sale environment](/device-environments) required. #### Path Parameters | Name | Type | Description | | ------ | ------------------- | ----------------------------------- | | action | TicketsUpdateAction | Specifies ticket batch update mode. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfully patched." %} ```javascript { "id": "635f70e1fa3dab15784a0b45", "externalId": null, "state": "Open", "type": "CashRegister", "name": "7", "openDate": "2022-10-31T06:53:20.76Z", "issueDate": null, "closeDate": null, "closeInfo": null, "purchaseType": "WalkIn", "location": { "zoneName": "Bar", "tableName": "B7" }, "customer": { "id": null, "externalId": null, "cardSerialNumber": "customer-card-serial-number", "firstName": null, "lastName": null, "fullName": "John Doe", "gender": null, "birthDate": null, "address": null, "deliveryAddress": null, "isCompany": false, "company": null, "phone": null, "email": null, "creditRate": null, "meta": {} }, "originDeviceName": "P01", "employee": { "name": "Mr. Waiter", "userName": "1", "featureName": null }, "items": [ { "id": 1, "externalId": null, "type": "Positive", "plu": { "name": "Cappucino", "description": null, "stockName": "S01", "code": 9, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.083333, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 2, "externalId": null, "type": "Positive", "plu": { "name": "Espresso Doppio", "description": null, "stockName": "S01", "code": 7, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.166667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 3, "externalId": null, "type": "Positive", "plu": { "name": "Espresso", "description": null, "stockName": "S01", "code": 1, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 1.416667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 4, "externalId": null, "type": "Positive", "plu": { "name": "Mlieko", "description": null, "stockName": "S01", "code": 49, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 0.25, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null } ], "payments": [], "currencyLabel": "EUR", "discountRate": 5.0, "roundingAmount": null, "invoiceNumber": null, "paragonNumber": null, "isParagon": false, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Delete ticket `DELETE` `http://{server-address}/tickets/{id}` **Required rights** Please see [User rights required for deleting ticket](/api-reference/tickets/ticket-operations-and-user-rights#deleting-ticket) section. **Required environments** [Sale environment](/device-environments) required. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------------ | | id\* | string | Unique ticket identifier | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "id": "635f70e1fa3dab15784a0b45", "externalId": null, "state": "Open", "type": "CashRegister", "name": "7", "openDate": "2022-10-31T06:53:20.76Z", "issueDate": null, "closeDate": null, "closeInfo": null, "purchaseType": "WalkIn", "location": { "zoneName": "Bar", "tableName": "B7" }, "customer": { "id": null, "externalId": null, "cardSerialNumber": "customer-card-serial-number", "firstName": null, "lastName": null, "fullName": "John Doe", "gender": null, "birthDate": null, "address": null, "deliveryAddress": null, "isCompany": false, "company": null, "phone": null, "email": null, "creditRate": null, "meta": {} }, "originDeviceName": "P01", "employee": { "name": "Mr. Waiter", "userName": "1", "featureName": null }, "items": [ { "id": 1, "externalId": null, "type": "Positive", "plu": { "name": "Cappucino", "description": null, "stockName": "S01", "code": 9, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.083333, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 2, "externalId": null, "type": "Positive", "plu": { "name": "Espresso Doppio", "description": null, "stockName": "S01", "code": 7, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.166667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 3, "externalId": null, "type": "Positive", "plu": { "name": "Espresso", "description": null, "stockName": "S01", "code": 1, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 1.416667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 4, "externalId": null, "type": "Positive", "plu": { "name": "Mlieko", "description": null, "stockName": "S01", "code": 49, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 0.25, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null } ], "payments": [], "currencyLabel": "EUR", "discountRate": 5.0, "roundingAmount": null, "invoiceNumber": null, "paragonNumber": null, "isParagon": false, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## RPC Actions These API methods trigger specific actions on server. However, it's important to note that depending on the type of selected [fiscal device](/data-models#fiscal) or [order endpoint device](/data-models#orderendpoint), some methods may not be supported. Furthermore, if an action is attempted on an inactive [fiscal device](/data-models#fiscal) or [order endpoint device](/data-models#orderendpoint), it will lead to failure. In both scenarios, making API calls will generate an HTTP status code of 403. ## Close ticket `POST` `http://{server-address}/tickets/{id}/close` Fiscalizes specific ticket (prints receipt or sends email receipt)and changes it's state to *closed*. Request body contains `TicketCloseContext` class. [Ticket](/data-models#ticket) is returned in response body. **Required rights** Please see [User rights required for closing ticket](/api-reference/tickets/ticket-operations-and-user-rights#closing-ticket) section. **Required environments** [Sale environment](/device-environments) required. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------------- | | id\* | string | Unique ticket identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------------------ | ------------------ | | (body)\* | TicketCloseContext | The close options. | {% tabs %} {% tab title="200: OK Ticket is successfully closed." %} ```json { "id": "635f70e1fa3dab15784a0b45", "externalId": null, "state": "Closed", "type": "CashRegister", "name": "7", "openDate": "2022-10-31T06:53:20.76Z", "issueDate": null, "closeDate": "2022-10-31T07:05:43Z", "closeInfo": { "eKasa": null, "dailySalesReportNumber": 123, "number": 3, "fiscalMemorySerialNumber": "347...005", "fiscalName": "eKasa", "deviceName": "P01" }, "purchaseType": "WalkIn", "location": { "zoneName": "Bar", "tableName": "B7" }, "customer": { "id": null, "externalId": null, "cardSerialNumber": "customer-card-serial-number", "firstName": null, "lastName": null, "fullName": "John Doe", "gender": null, "birthDate": null, "address": null, "deliveryAddress": null, "isCompany": false, "company": null, "phone": null, "email": null, "creditRate": null, "meta": {} }, "originDeviceName": "P01", "employee": { "name": "Mr. Waiter", "userName": "1", "featureName": null }, "items": [ { "id": 1, "externalId": null, "type": "Positive", "plu": { "name": "Cappucino", "description": null, "stockName": "S01", "code": 9, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.083333, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 2, "externalId": null, "type": "Positive", "plu": { "name": "Espresso Doppio", "description": null, "stockName": "S01", "code": 7, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 2.166667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 3, "externalId": null, "type": "Positive", "plu": { "name": "Espresso", "description": null, "stockName": "S01", "code": 1, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 1.416667, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null }, { "id": 4, "externalId": null, "type": "Positive", "plu": { "name": "Mlieko", "description": null, "stockName": "S01", "code": 49, "articleCategoryLabel": "KAV", "vatInfo": { "category": 1, "rate": 20.0 }, "isDiscountAllowed": true, "isPriceFixed": true, "isSplittable": true, "orderEndpointNames": [ "Bar" ], "type": "Recipe", "specialRegulation": null, "isCashbackAllowed": true }, "comment": null, "unitPrice": { "amount": 0.25, "currencyLabel": "EUR" }, "quantity": { "amount": 1.0, "unit": "ks" }, "discountRate": 0.0, "referenceFiscalTicketId": null, "voucherNumber": null, "isQuantityFixed": false, "courseNumber": null, "subItems": null } ], "payments": [ { "paymentType": { "number": 2, "description": "Kreditná karta", "isChangeable": false, "category": "CreditCard" }, "amount": { "amount": 6.73, "currencyLabel": "EUR", "domesticCurrencyLabel": "EUR", "exchangeRate": 1.0 } } ], "currencyLabel": "EUR", "discountRate": 5.0, "roundingAmount": { "amount": 0.0, "currencyLabel": "EUR" }, "invoiceNumber": null, "paragonNumber": null, "isParagon": false, "_v": 2 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Print preliminary ticket `POST` `http://{server-address}/tickets/{id}/print_preliminary_ticket` Prints *preliminary receipt* on specified [order endpoint](/data-models#orderendpoint). A preliminary receipt, often referred to as a "pre-check" or "provisional bill," is a document provided to diners before they make the final payment for their meal. This receipt outlines the items ordered and their associated costs, offering customers an initial overview of their expenses. This lets customer review the details before the final bill is issued. The ticket's state remains unchanged. This action can be executed on both opened and closed tickets. **Required rights** Please see [User rights required for ](/api-reference/tickets/ticket-operations-and-user-rights#closing-ticket)[printing preliminary ticket](/api-reference/tickets/ticket-operations-and-user-rights#printing-preliminary-ticket) section. **Required environments** [Sale environment](/device-environments) required. #### Path Parameters | Name | Type | Description | | ------ | ------------------- | ----------------------------------- | | action | TicketsUpdateAction | Specifies ticket batch update mode. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | (body) | PrintPreliminaryTicketContext | The [`PrintPreliminaryTicketContext`](/data-models#printpreliminaryticketcontext) object containing preliminary receipt printing options. | {% tabs %} {% tab title="204: No Content Preliminary ticket successfully printed." %} The response contains no content. {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Ticket Model States Understanding the Various Phases of Tickets A [ticket](/data-models#ticket), depending on its state, represents either a customer order or a printed receipt. The ticket has two defined states: * **Opened**: Represents a customer order that has not been paid yet. * **Closed**: Once the ticket is printed on the receipt printer (or sent as e-mail receipt), it is marked as closed and becomes uneditable. You can determine whether a ticket is closed by checking the value of the `closeInfo` and `closeDate` properties. If the value both properties is `null`, the ticket is *open* and can be edited. If the values are not `null`, the ticket is *closed*, and the `closeInfo` value contains information about the closing procedure. This information includes details such as the [fiscal printer](/api-reference/fiscals) name, receipt sequence number and the unique receipt identifier provided by the tax authority (Finančná správa in Slovakia). # Ticket Operations and User Rights Navigating Access for Ticket Actions This section describes [user rights](#user-rights) required when performing [Ticket API methods](/api-reference/tickets). ## **Creating and modifying ticket** When creating or modifying [ticket](/data-models#ticket), specific [user rights](/user-rights) are required, based on payload data and whether ticket with given identifier already exists. * `TicketCreate`: necessary when no existing ticket with given identifier is found. * `TicketUpdate`: necessary when attempting to modify an open ticket with a given identifier. This applies when the ticket is linked to an authorized user (determined through the `employee.userName` property). * `TicketUpdateAny`: necessary when attempting to modify an open ticket with a given identifier. This applies when the ticket is linked to a user other than the authorized user (determined through the `employee.userName` property). * `TicketRename`: necessary when attempting to modify `name` property of an existing open ticket. * `TicketSetDiscount`: necessary when attempting to set a non-zero value for the `discountRate` property of a new ticket or changing it from an existing ticket. If the ticket is associated with a [customer](/data-models#customer) (through the `customer` property), setting a value equal to the customer's discount rate (`customer.discountRate`) is allowed and doesn't require this right. * `TicketSetCustomer`: necessary when attempting to set non-null value for `customer` property of a new ticket or changing it for an existing ticket. * `TicketHandover`: necessary when attempting to associate ticket with user other than the authorized user (determined through the `employee.userName` property). * `TicketTakeover`: necessary when attempting to switch the association of a ticket from a user other than the authorized user (identified through the `employee.userName` property) to the authorized user. The execution of this operation also required `TicketUpdateAny` [user right](/user-rights). ## **Deleting ticket** When deleting existing opened ticket, specific [user rights](/user-rights) are required, based on properties of existing ticket. * `TicketDelete`: neccessary when deleting ticket associated with authorized user (determined through the `employee.userName` property). * `TicketUpdateAny`: necessary deleting ticket linked to a user other than the authorized user (determined through the `employee.userName` property). * `Storno`: necessary when deleting ticket containing at least one [ticket item](/data-models#ticketitem) in `items` collection with a quantity greater than zero. ## Closing ticket When closing ticket, following [user rights](#user-rights) are required: * `TicketClose`: necessary when closing ticket. * `TicketCloseAny`: necessary when closing ticket linked to a user other than the authorized user (determined through the `employee.userName` property). * `TicketCloseAs`: necessary when closing ticket in behalf of user other than the authorized user (determined through the `user.userName` property of [`TicketCloseContext`](/data-models#ticketclosecontext)). * `TicketCloseToAnyFiscal`: necessary when closing a ticket on a [fiscal device](/data-models#fiscal) that is not the *default* fiscal device. For more details on how to evaluate the default fiscal device, please refer to the [Evaluating the Default Fiscal Name](#evaluating-the-default-fiscal-name) section. * `TicketUpdate`: necessary when ticket is linked to an authorized user (determined through the `employee.userName` property). * `TicketUpdateAny`: necessary when ticket is linked to a user other than the authorized user (determined through the `employee.userName` property). ### **Evaluating the Default Fiscal Name** This section outlines the procedure for determining the default [fiscal device](/data-models#fiscal) for a [ticket](/data-models#ticket) 1. **Using Zone's defaultFiscalName Property:** The default fiscal name is extracted from the `defaultFiscalName` property of the [Zone](/data-models#zone) linked to the [Ticket](/data-models#ticket) through the [Ticket](/data-models#ticket)'s `location` property. If the `location` property is empty (equal to `null`), move on to the next step. 2. **Checking Device's Settings.DefaultFiscalName Property:** The `Settings.DefaultFiscalName` property of the [Device](/data-models#device) associated with the authorized user is checked. If the property value is equal to `null`, proceed to the next step. 3. **No Default Fiscal Name Set:** If none of the above steps yield a default fiscal name, it means that the default fiscal name is not configured. In such cases, the `TicketCloseToAnyFiscal` [user right](/user-rights) is not required. ## Printing preliminary ticket When printing preliminary ticket, following [user rights](#user-rights) are required: * `TicketPrintPreliminary` * `TicketUpdate`: necessary when ticket is linked to an authorized user (determined through the `employee.userName` property). * `TicketUpdateAny`: necessary when ticket is linked to a user other than the authorized user (determined through the `employee.userName` property). # Ticket Model Mathematics Exploring calculations and logic within Tickets and Ticket Items The [Ticket](/data-models#ticket) model is defined without supplementary financial properties. Instead, these additional properties can be calculated on the client's side. This article explains how the math works in the [Ticket](/data-models#ticket) model and related models like [`TicketItem`](/data-models#ticketitem). {% hint style="info" %} **Understanding Property Naming Conventions** When a financial property doesn't have the "*IncludingVat*" postfix, its value is indicated without including VAT. For instance, `unitPrice` refers to the value excluding VAT, while `unitPriceIncludingVat` specifies the value including VAT. {% endhint %} ## Ticket Item Mathematics The [`ticketItem`](/data-models#ticketitem) model contains following properties, relevant for mathematics: * `unitPrice`: price per single quantity unit, excluding VAT. * `quantity.amount`: the amount of product or service * `discountRate`: the discount rate (numeric value between 0 and 100). * `plu.vatInfo.Rate`: VAT rate percentage * `plu.isDiscountAllowed`: indicates whether discount can be applied to ticket item ### Unit Price Including VAT Initially, we must calculate VAT from the base amount, using the following formula: $$ vat = unitPrice \* ( vatRate / 100) $$ The "vatRate" refers to `plu.vatInfo.rate`. The outcome of *vat* is expressed as a [UnitPrice](/data-models#unitprice), rounded mathematically to six decimal places, refered as "*vat rounded*". The unit price including VAT of [ticket item](/data-models#ticketitem) is then calculated using following formula: $$ unitPriceIncludingVat = unitPrice + vat\_{rounded} $$ The outcome of second formula is expressed as a [UnitPrice](/data-models#unitprice), rounded mathematically to six decimal places as well. ### Effective Discount Rate The discount can be placed on ticket item based on two properties: * The discount rate of the [ticket](/data-models#ticket) in which the [ticket item](/data-models#ticketitem) is located (the `ticket.discountRate` property, referred to as "*dt*" in the formula below)*.* The value is normalized within an interval between 0 and 1, with the value rounded mathematically to four decimal places. * The discount rate of the [ticket item](/data-models#ticketitem) itself (the `ticketItem.discountRate` property, referred to as "*di*" in the formula below). The value is normalized within an interval between 0 and 1, with the value rounded mathematically to four decimal places. The effective discount rate (referred to as "*de"*) is calculated using the following formula: $$ d\_{e}= 1- (1 - d\_{t}) \* (1 - d\_{ti}) $$ The outcome is value within an interval between 0 and 1, with the value rounded mathematically to four decimal places. ### Unit Price After Discount The `plu.isDiscountAllowed` specifies, whether discount can be applied to ticket item. When value is `false`, unit price *after discount* is equal to unit price. However, when `plu.isDiscountAllowed` is set to `true`, the following formula is used to calculate the unit price after applying a discount: $$ unitPriceIncludingDiscount = unitPrice - unitPrice \* d\_{e} $$ The "*de"* refers to [effective discount rate](#effective-discount-rate). The outcome is expressed as a [UnitPrice](/data-models#unitprice), rounded mathematically to six decimal places. ### Unit Price After Discount Including VAT The `plu.isDiscountAllowed` specifies, whether discount can be applied to ticket item. When value is `false`, unit price *after discount* including VAT is equal to unit price including VAT. However, when `plu.isDiscountAllowed` is set to `true`, the following formula is used to calculate the unit price after applying a discount, including VAT: $$ unitPriceAfterDiscountIncludingVat = up - up \* d\_{e} $$ * The "*up*" refers to [unit price including VAT](#unit-price-including-vat). The "*d*_*e**"* refers to [effective discount rate](#effective-discount-rate). The outcome is expressed as a [UnitPrice](/data-models#unitprice), rounded mathematically to six decimal places. ### Total Price Including VAT The following formula is used to calculate the total price of a [ticket item](/data-models#ticketitem), including VAT: $$ totalPriceIncludingVat = unitPriceIncludingVat \* quantity $$ The "*quantity*" refers to `quantity.amount`. The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. ### Total Price After Discount Including VAT The following formula is used to calculate the total price of a [ticket item](/data-models#ticketitem) after applying a discount, including VAT: $$ totalPriceAfterDiscountIncludingVat = up \* quantity $$ The "*up*" refers to [unit price after discount including VAT](#unit-price-after-discount-including-vat). The "*quantity*" refers to `quantity.amount`. The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. When a `TicketItem` contains subitems, the formula to calculate the total price after applying a discount, including VAT, involves adding the sum of the total prices of all subitems: $$ totalPriceAfterDiscountIncludingVat = (up \* quantity) + \sum\_{i=1}^{n}(subitemPrice\_{i} \* quantity) $$ Here, each `subitemPrice` refers to the [total price after discount including VAT](#total-price-after-discount-including-vat) for each subitem. The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. ### Discount Price Including VAT The following formula is used to calculate the total discount of a [ticket item](/data-models#ticketitem) including VAT: $$ discountPriceIncludingVat = tp - tp\_{d} $$ The "tp" refers to [total price including VAT](#total-price-including-vat). The "*tpd*" refers to [total price after discount including VAT](#total-price-after-discount-including-vat). The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. ## Ticket Mathematics The [`ticket`](/data-models#ticket) model contains following properties, relevant for mathematics: * `discountRate`: the discount rate (numeric value between 0 and 100). * `items`: collection of [ticket items](/data-models#ticketitem). * `payments`: collection of [ticket payments](/data-models#ticketpayment). * `roundingAmount`: the rounding amount. * `type`: certain formulas might differ depending on the [ticket type](/data-models#tickettype). For instance, if the ticket is of the `invoice` [type](/data-models#tickettype), it won't have any elements in the \`items\` collection. ### Payments amount of Ticket Total amount of payments. $$ paymentsAmount = Σ (p ∈ payments) p.amount.amount $$ The notation represents the summation of the `amount.amount` property for each [ticket payment](/data-models#ticketpayment) within the `payments` collection. The expression `p ∈ payments` indicates the iteration over each element in the payments collection. The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. ### Total Price of Ticket Including VAT Total [ticket](/data-models#ticket) amount, including VAT, before any discounts are applied. If ticket is of the `invoice` [type](/data-models#tickettype), total price including VAT is equal to [payments amount](#payments-amount). Othewise, total price including VAT is calculated using the following formula: $$ totalPriceIncludingVat = Σ (i ∈ items) i.totalPriceIncludingVat $$ The notation represents the summation of the `totalPriceIncludingVat` property for each [ticket item](/data-models#ticketitem) within the `items` collection. The expression `i ∈ items` indicates the iteration over each element in the items collection. The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. ### Total Price After Discount of Ticket Including VAT Total [ticket](/data-models#ticket) amount, including VAT, after discounts are applied. If ticket is of the `invoice` [type](/data-models#tickettype), total price after discount including VAT is calculated using the following formula: $$ t\_{invoice} = paymentsAmount - roundingAmount $$ The "*paymentsAmount*" refers to [payments amount of ticket](#payments-amount-of-ticket). The "*roundingAmount*" refers to `roundingAmount` property of [ticket](/data-models#ticket). The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. Otherwise, if ticket is not of `invoice` [type](/data-models#tickettype), total price after discount including VAT is calculated using the following formula: $$ t\_{cashRegister} = Σ (i ∈ items) i.totalPriceAfterDiscountIncludingVat $$ The notation represents the summation of the [total price after discount including VAT](#total-price-after-discount-including-vat) for each [ticket item](/data-models#ticketitem) within the `items` collection. The expression `i ∈ items` indicates the iteration over each element in the items collection. The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. ### Total Price after Discount of Ticket Including VAT and Rounding Total [ticket](/data-models#ticket) amount, including VAT and rounding, after discounts are applied. If ticket is of the `invoice` [type](/data-models#tickettype), total price after discount including VAT and rounding equal to [payments amount of ticket](#payments-amount-of-ticket). Otherwise, if ticket is not of `invoice` [type](/data-models#tickettype), total price after discount including VAT and rounding is calculated using the following formula: $$ totalPriceAfterDiscountIncludingVat + roundingAmount $$ The "*totalPriceAfterDiscountIncludingVat*" refers to [total price after discount of Ticket including VAT](#total-price-after-discount-of-ticket-including-vat). The "*roundingAmount*" refers to `roundingAmount` property of [ticket](/data-models#ticket). The outcome is expressed as a [Price](/data-models#price), rounded mathematically to two decimal places. ## Examples ### Example 1 Assume [ticket item](/data-models#ticketitem) with the following properties: * unit price = 5.363636 * quantity = 1.234 * discount rate = 20% * vat rate = 10% * is discount allowed = yes Unit price including VAT, VAT must be is calculated first, using following formula: $$ vat = unitPrice \* ( vatRate / 100) = 5.363636 \* (10 / 100) = 0.5363636 $$ To get rounded VAT, result must be rounded to 6 decimal places: $$ 0.5363636 ≈ 0.536364 $$ To calculate unit price including VAT, we use formula: $$ unitPriceIncludingVat = unitPrice + vat\_{rounded} = 5.363636 + 0.536364 = 5.90 $$ To calculate effective discount rate, we use formula: $$ d\_{e}= 1 - (1 - d\_{t}) \* (1 - d\_{ti}) = 1-(1-0)*(1-0.2) = 1-(1*0.8)=0.2 $$ To calculate unit price after discount including VAT, we use formula: $$ up - up \* d\_{e} = 5.90 - 5.90 \* 0.2 = 5.90 - 1.18 = 4.72 $$ To calculate total price including VAT, we use formula: $$ totalPriceIncludingVat = unitPriceIncludingVat \* quantity = 5.90 \* 1.234 ≈ 7.28 $$ To calculate total price after discount including VAT, we use formula: $$ totalPriceAfterDiscountIncludingVat = up \* quantity = 4.72 \* 1.234 ≈ 5.82 $$ # Users This page provides a description of the available API routes for managing users. Every person that uses the system has their own [user profile](/data-models#userprofile), which contains a collection of [devices](/data-models#device) that the user is allowed to log into. For each device, the user can be granted different rights. ## API methods ## Get users `GET` `http://{server-address}/users` Returns all users that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | isActive | bool | Supports NData syntax. | | isVirtual | bool | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | | featureName | string | Supports NData syntax. | | userName | string | Supports NData syntax. | | name | string | Supports NData syntax. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "id": "62ffb6c57028d4f9c14f0fc1", "isActive": true, "isVirtual": false, "userName": "999", "featureName": null, "name": "Majiteľ", "devices": [ { "isActive": true, "envName": "CashRegister", "name": "P01", "roles": [ "admin" ], "description": "Pokladňa 01", "preferences": {} }, { "isActive": true, "envName": "BackOffice", "name": "BackOffice", "roles": [ "admin" ], "description": "BackOffice", "preferences": {} }, { "isActive": true, "envName": "Tool", "name": "mPOS Link", "roles": [ "admin" ], "description": "mPOS Link", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA1", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA2", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "CashRegister", "name": "P02", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} } ], "hasPassword": false, "_v": 4 }, { "id": "63260d6e046c7b515ea93beb", "isActive": true, "isVirtual": true, "userName": "Qerko", "featureName": "Portos.Features.Qerko", "name": "Qerko", "devices": [ { "isActive": true, "envName": "System", "name": "SYSTEM", "roles": [ "admin" ], "description": null, "preferences": {} } ], "hasPassword": false, "_v": 1 } ], "count": 2, "totalCount": 2 } ``` {% endtab %} {% endtabs %} ## Get user `GET` `http://{server-address}/users/{id}` Result is of type [UserProfile](/data-models#userprofile). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ----------------------- | | id\* | string | Unique user identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Resource found." %} ```javascript { "id": "62ffb6c57028d4f9c14f0fc1", "isActive": true, "isVirtual": false, "userName": "999", "featureName": null, "name": "Majiteľ", "devices": [ { "isActive": true, "envName": "CashRegister", "name": "P01", "roles": [ "admin" ], "description": "Pokladňa 01", "preferences": {} }, { "isActive": true, "envName": "BackOffice", "name": "BackOffice", "roles": [ "admin" ], "description": "BackOffice", "preferences": {} }, { "isActive": true, "envName": "Tool", "name": "mPOS Link", "roles": [ "admin" ], "description": "mPOS Link", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA1", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA2", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "CashRegister", "name": "P02", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} } ], "hasPassword": false, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found User is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create user `POST` `http://{server-address}/users` Creates new user. Method accepts [`UserCreateUpdateContext`](/data-models#usercreateupdatecontext) in the request body. Result is of type [UserProfile](/data-models#userprofile). **Required rights** Authorized user must have `UserCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ----------------------- | ------------------------------ | | (body)\* | UserCreateUpdateContext | Context create or update user. | {% tabs %} {% tab title="201: Created Successfuly created." %} ```javascript { "id": "62ffb6c57028d4f9c14f0fc1", "isActive": true, "isVirtual": false, "userName": "999", "featureName": null, "name": "Majiteľ", "devices": [ { "isActive": true, "envName": "CashRegister", "name": "P01", "roles": [ "admin" ], "description": "Pokladňa 01", "preferences": {} }, { "isActive": true, "envName": "BackOffice", "name": "BackOffice", "roles": [ "admin" ], "description": "BackOffice", "preferences": {} }, { "isActive": true, "envName": "Tool", "name": "mPOS Link", "roles": [ "admin" ], "description": "mPOS Link", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA1", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA2", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "CashRegister", "name": "P02", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} } ], "hasPassword": false, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update user `PUT` `http://{server-address}/users/{id}` Updates existing or creates new user. Method accepts [`UserCreateUpdateContext`](/data-models#usercreateupdatecontext) in the request body. Result is of type [UserProfile](/data-models#userprofile). **Required rights** Authorized user must have assigned `UserCreate` or `UserUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ----------------------- | | id\* | string | Unique user identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ----------------------- | ------------------------------ | | (body)\* | UserCreateUpdateContext | Context create or update user. | {% tabs %} {% tab title="200: OK Successfuly created or updated." %} ```javascript { "id": "62ffb6c57028d4f9c14f0fc1", "isActive": true, "isVirtual": false, "userName": "999", "featureName": null, "name": "Majiteľ", "devices": [ { "isActive": true, "envName": "CashRegister", "name": "P01", "roles": [ "admin" ], "description": "Pokladňa 01", "preferences": {} }, { "isActive": true, "envName": "BackOffice", "name": "BackOffice", "roles": [ "admin" ], "description": "BackOffice", "preferences": {} }, { "isActive": true, "envName": "Tool", "name": "mPOS Link", "roles": [ "admin" ], "description": "mPOS Link", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA1", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA2", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "CashRegister", "name": "P02", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} } ], "hasPassword": false, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Delete user `DELETE` `http://{server-address}/users/{id}` **Required rights** Authorized user must have `UserDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ----------------------- | | id\* | string | Unique user identifier. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successfuly deleted." %} ```javascript { "id": "62ffb6c57028d4f9c14f0fc1", "isActive": true, "isVirtual": false, "userName": "999", "featureName": null, "name": "Majiteľ", "devices": [ { "isActive": true, "envName": "CashRegister", "name": "P01", "roles": [ "admin" ], "description": "Pokladňa 01", "preferences": {} }, { "isActive": true, "envName": "BackOffice", "name": "BackOffice", "roles": [ "admin" ], "description": "BackOffice", "preferences": {} }, { "isActive": true, "envName": "Tool", "name": "mPOS Link", "roles": [ "admin" ], "description": "mPOS Link", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA1", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "PDA", "name": "PDA2", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} }, { "isActive": true, "envName": "CashRegister", "name": "P02", "roles": [ "sale", "statsCurrent", "statsTicketsCurrent", "openDrawer", "negativeSale", "overviewSalesReport", "ticketSplit", "storno", "stats", "statsPlus", "cashTransfer", "allTickets", "ticketSetDiscount", "admin" ], "description": "", "preferences": {} } ], "hasPassword": false, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Given resource was not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Vats This page provides a description of the available API routes for managing VAT rates. Each VAT rate is identified by its numeric category identifier and associated VAT rate with value between 0 and 100. The VAT data model is represented by [`Vat`](/data-models#vat) class. ## API methods ## Get VATs `GET` `http://{server-address}/vats` Returns all VATs that matches query parameters. Result is of type [`QueryResult`](/data-models#queryresult). #### Query Parameters | Name | Type | Description | | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | category | decimal | Supports NData syntax. | | rate | decimal | Supports NData syntax. | | $skip | int | Pagination property. Describing number of records to skip from beginning of result collection. | | $take | int | Pagination property. Maximum count of items to be returned. | | $sort | string\[] |

Comma separated list of property names. Please see NData syntax.

| | $count | bool | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK Successful response" %} ```javascript { "items": [ { "name": "Bar", "defaultFiscalName": null, "items": [ { "name": "B01", "isTable": true, "meta": { "position": { "x": 0.10, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } }, { "name": "B02", "isTable": true, "meta": { "position": { "x": 0.30, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } } ], "sortHint": 1, "_v": 1 } ], "count": 1, "totalCount": 1 } ``` {% endtab %} {% endtabs %} ## Get zone by name `GET` `http://{server-address}/zones/{name}` Result is of type [Zone](/data-models#zone). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ----------------- | | name\* | string | Unique zone name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK " %} ```javascript { "name": "Bar", "defaultFiscalName": null, "items": [ { "name": "B01", "isTable": true, "meta": { "position": { "x": 0.10, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } }, { "name": "B02", "isTable": true, "meta": { "position": { "x": 0.30, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } } ], "sortHint": 1, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found Zone with given name is not found." %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} ## Create zone `POST` `http://{server-address}/zones` Creates new zone. Result is of type [Zone](/data-models#zone). **Required rights** Authorized user must have `ZoneCreate` [right ](/user-rights)assigned. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ---- | -------------------- | | (body)\* | Zone | Zone model to create | {% tabs %} {% tab title="201: Created " %} ```javascript { "name": "Bar", "defaultFiscalName": null, "items": [ { "name": "B01", "isTable": true, "meta": { "position": { "x": 0.10, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } }, { "name": "B02", "isTable": true, "meta": { "position": { "x": 0.30, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } } ], "sortHint": 1, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Create or update zone `PUT` `http://{server-address}/zones/{name}` Updates existing or creates new zone. Result is of type [Zone](/data-models#zone). **Required rights** Authorized user must have assigned `ZoneCreate` or `ZoneUpdate` [right](/user-rights). #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ----------------- | | name\* | string | Unique zone name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ---- | ------------------------------- | | (body)\* | Zone | Zone model to create or update. | {% tabs %} {% tab title="200: OK " %} ```javascript { "name": "Bar", "defaultFiscalName": null, "items": [ { "name": "B01", "isTable": true, "meta": { "position": { "x": 0.10, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } }, { "name": "B02", "isTable": true, "meta": { "position": { "x": 0.30, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } } ], "sortHint": 1, "_v": 1 } ``` {% endtab %} {% endtabs %} ## Delete zone by name `DELETE` `http://{server-address}/zones/{name}` **Required rights** Authorized user must have `ZoneDelete` [right ](/user-rights)assigned. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ----------------- | | name\* | string | Unique zone name. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------- | | Authorization\* | string | Authorization header with authorization token. | {% tabs %} {% tab title="200: OK " %} ```javascript { "name": "Bar", "defaultFiscalName": null, "items": [ { "name": "B01", "isTable": true, "meta": { "position": { "x": 0.10, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } }, { "name": "B02", "isTable": true, "meta": { "position": { "x": 0.30, "y": 0.10 }, "width": 0.12, "height": 0.12, "shape": "Rectangle", "rotation": 0, "color": "#cccccc" } } ], "sortHint": 1, "_v": 1 } ``` {% endtab %} {% tab title="404: Not Found " %} ```javascript { "title": "Zdroj nebol nájdený", "status": 404 } ``` {% endtab %} {% endtabs %} # Introduction {% tabs %} {% tab title="Enhlish 🇬🇧" %} This section provides an overview of the different integration points between the PORTOS system and third-party applications or systems. In the PORTOS system, a universal API connector is designed for each area, facilitating communication between third-party applications and the PORTOS system {% endtab %} {% tab title="Slovensky 🇸🇰 " %} Táto časť popisuje rôzne oblasti integrácie medzi systémom PORTOS a aplikáciami alebo systémami tretích strán. V systéme PORTOS je pre každú oblasť navrhnutý univerzálny API konektor, prostredníctvom ktorého aplikácia tretej strany so systémom PORTOS komunikuje. {% endtab %} {% endtabs %} | Integration interface | Field of use | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | [Online orders API](/integrations/online-orders-api) | Integration with food delivery platforms, booking systems or custom e-shops with ability to order food or submit a table reservation. | | [Rewards API](/integrations/rewards-api) | Ability to provide vouchers, coupons, rewards or deals for your customers. | | [PDA Files](/integrations/pda-files) | Minimal approach to transfer tickets from external system to PORTOS using text files. | # Online orders API Transporting orders from e-shops or food delivery platforms to the PORTOS application. ## Glossary | Term | Definition | | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | | Term | Definition | | PORTOS | The cash register solution developed by Nine Digit, s.r.o. | | External system | The 3rd party system (such as e-shop or food delivery platform) from which unprocessed orders are imported to PORTOS. | | Venue | The restaurant processing the order. | | Cashier | The Venue personnel | | Customer | User who orders the goods trough external system. | | Order | The purchase request made by customer trough the external system, containing data about products, delivery address, etc. | | Unprocessed order | Order accepted by external system, but not yet confirmed nor rejected by PORTOS. | | Processed order | Order confirmed or rejected by PORTOS. | | Product | The product (such as food or drink) that is ordered by customer. | ## How it works The online orders API is a mechanism that allows importing online orders from "external system" (such as e-shops or food delivery platforms) to the PORTOS system. The PORTOS system acts as an "client" initiating HTTP requests targeting the *external system*, that acts as an "server" and handles the following requests: 1. Fetch unprocessed orders 2. Process order After unprocessed order is fetched, cashier is requested to process (either accept or reject) the order trough the PORTOS application. After cashier confirms or rejects the order, PORTOS application will initiate second request (*process order*) to the *external system.* The PORTOS system expects that responses from *external system* follows data format described below. ## Fetch unprocessed orders `GET` `{external-system}{unprocessed-orders-url}` The PORTOS system will periodically fetch the unprocessed orders from the external system, by initiating GET HTTP request to the external system. External system returns the unprocessed orders for given venue. If the collection of orders is paginated by the external system (so response does not contain all unprocessed orders), the most oldest orders should be returned. #### Query Parameters | Name | Type | Description | | ------- | ------ | ---------------------------------------------------------------------------- | | version | string | The version of the exchange protocol. For versions 1.X, value is set to `1`. | | key | string | The API key. | {% tabs %} {% tab title="200 " %} ```javascript [ { "id": "b478396ad654", "type": "delivery", "delivery": { "address": { "line1": "Kresankova 12", "line2": "", "city": "Bratislava", "zipCode": 84105, "note": "Please knock twice" }, "fee": 1.99 }, "createdAt": "2021-02-01T12:01:00.000Z", "scheduledAt": null, "customer": { "name": "John Doe", "phone": "+421 900 123 456", "email": "john.doe@example.com" }, "products": [ { "id": "1234", "name": "Burger", "quantity": 1, "baseUnitPrice": 8.99, "note": "", "additions": [ { "id": "11002", "name": "No cheese", "quantity": 1, "unitPrice": 0.00, "note": "" }, { "id": "11002", "name": "Extra bacon", "quantity": 1, "unitPrice": 1.99, "note": "" } ] } ], "currency": "EUR", "payment": { "isSettled": true, "method": "card" }, "tip": 0, "totalPrice": 12.97, "note": null }, { "id": "6a2ad048e32d", "type": "takeAway", "delivery": null, "createdAt": "2021-02-01T12:01:00.000Z", "scheduledAt": "2021-02-01T13:00:00.000Z", "customer": { "name": "John Doe", "phone": "+421 900 123 456", "email": "john.doe@example.com" }, "products": [ { "id": "2345", "name": "Fries", "quantity": 2, "baseUnitPrice": 4.99, "note": "", "additions": [ { "id": "11024", "name": "Ketchup", "quantity": 1, "unitPrice": 1.99, "note": "" } ] } ], "currency": "EUR", "payment": { "isSettled": false, "method": null }, "wrappingFee": 0, "packagingDeposit": 0, "tip": 0, "totalPrice": 13.96, "note": null } ] ``` {% endtab %} {% tab title="401 The bearer authorization token is invalid." %} ``` { "message": "This is the optional message describing the error." } ``` {% endtab %} {% tab title="403 The orders cannot be fetched. The reason may be provided in body." %} ``` { "message": "This is the optional message describing the error." } ``` {% endtab %} {% endtabs %} ## Process order `POST` `{external-system}{process-order-url}` After the order is confirmed or rejected by Cashier trough the PORTOS cash register system user interface, the PORTOS system will initiate the POST HTTP request to the external system, to mark this specific order as processed. #### Query Parameters | Name | Type | Description | | --------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | version | string | The version of the exchange protocol. For versions 1.X, value is set to `1`. | | key | string | The API key. | | externalId | string | The external identifier of the order | | status | string | The order processing result. May be one of following: `accepted`, `rejected` | | estimatedCompletionAt | string |

The estimated date and time of order completion, formatted in ISO\_8601 format.

The meaning may vary based on order type:
- If order type is delivery: represents estimated time when products will be delivered to customer's address.
- If order type is takeAway: expected time that the order is ready to pick up at the Venue.
- If order type is dineIn, value is equal to order.scheduledAt (the time of reservation).

This value is provided only when the status is accepted. Value is not set (or equal to null), if order status is rejected.

| | rejectionReason | string | Briefly described reason of the rejection. Is optionally provided only when the status is `rejected`. | {% tabs %} {% tab title="200 The order confirmation or rejection has been acknowledged by the external system. The order will not longer appear in unprocessed orders response." %} ``` /* No response body is required by PORTOS. */ ``` {% endtab %} {% tab title="401 The bearer authorization token is invalid." %} ```javascript { "message": "This is the optional message describing the error." } ``` {% endtab %} {% tab title="403 The order has already been processed." %} ```javascript { "message": "This is the optional message describing the error." } ``` {% endtab %} {% endtabs %} ## Data model The data model of online orders exchange is described below. {% hint style="info" %} All prices include taxes. {% endhint %} ### Order Order represents purchase request made by customer trough the external system, containing data about products, delivery address, etc.

Name	Type	Required	Description
`externalId`	`string`	true	The unique identifier of order, generated by the external system.
`type`	`string` (please see allowed values)	false	The type of order. Contains one of following values:`delivery` (products will be delivered to customers address), `takeAway`(customer will pick up the order at the venue) or`dineIn`(customer will eat at the venue, e.g. table reservation). If type is not specified, `delivery` is used.
`delivery`	`OrderDelivery`	false	Information about the order delivery. Required, when `type` is `delivery`. Otherwise must be `null` (or not specified at all).
`createdAt`	`string`	true	The ISO_8601 formatted date and time of order creation (when the order has been created in external system).
`scheduledAt`	`string`	false	The optional ISO_8601 formatted date and time of scheduled order. If not specified, order should be delivered ASAP. This field is required when order type is `dineIn`.
`customer`	`Customer`	true	Customer contact information.
`products`	`Product[]`	true	The collection of products. Must contain at least one product.
`currency`	`string`	true	Currency code (in ISO 4217 standard) for order price information.
`payment`	`Payment`	false	The information about payment.
`wrappingFee`	`number`	false	Wrapping fee (not applicable in Slovak republic due to Slovak legislation).
`packagingDeposit`	`number`	false	Packaging deposit (associated with non-taxable VAT rate)
`tip`	`number`	false	Tip
`totalPrice`	`number`	true	Total price including VAT of order, including all products, product additions, delivery and wrapping fee. Precision up to 2 decimal places.
`note`	`string`	false	Optional comment related to the order.

### OrderDelivery Order delivery information.

Name	Type	Required	Description
`address`	`Address`	true	The delivery address.
`fee`	`number`	false	The cost of delivery including VAT. Precision up to 2 decimal places. If not specified, zero value will be used.

### Address The customer's address.

Name	Type	Required	Description
`line1`	`string`	true	1st line of delivery address (e.g. street name, building number)
`line2`	`string`	false	Optional 2nd line of delivery address.
`city`	`string`	true	Name of the city.
`zipCode`	`string`	true	The ZIP code (postal code).
`note`	string	false	Optional comment related to the address or delivery.

### Customer The customer's contact information.

Name	Type	Required	Description
Name	Type	Required	Description
`name`	`string`	Yes	Name of customer.
`phone`	`string`	Yes	Phone number.
`email`	`string`	No	E-mail address.

### Product The product (such as food or drink).

Name	Type	Required	Description
`id`	`string`	false	The product identifier in PORTOS system. If this field will not be provided, the processing of order will not affect stock quantity of the material in PORTOS stock management system.
`name`	`string`	true	Name of product.
`quantity`	`int`	true	Positive, non-zero integer quantity of the product (e.g. 1, 2, ...).
`baseUnitPrice`	`number`	true	The base unit price of product including VAT (product additions are not included). Both positive and negative value are supported. Use negative value to indicate discount.
`note`	`string`	false	The optional product-related comment, provided by customer.
`additions`	`ProductAddition[]`	false	The product additions (modifiers). If product `quantity` is greater than 1, each one will have same `additions` applied. Example #1: if customer orders two burgers with fries for each burger, order will contain product with name "Burger", quantity equal to 2 and addition with name "Fires" and quantity equal to one. Example #2: if customer orders two burgers, one with fries and second with salad. In this case, order will contain two separate products - first with quantity equal to one and fries in additions; second with quantity equal to one and salad in additions.

### ProductAddition The product addition (option, modifier) that adds more information about how the product should be prepared.

Name	Type	Required	Description
Name	Type	true	Description
`id`	`string`	false	The product identifier in PORTOS system. If this field will not be provided, the processing of order will not affect stock quantity of the material in PORTOS stock management system.
`name`	`string`	true	Name of product.
`quantity`	`int`	true	Positive, non-zero integer quantity of the product option (e.g. 1, 2, ...).
`unitPrice`	`number`	true	The unit price of product option, including VAT. Value may be positive or negative, if affects the price of product. Value also may be equal to zero, if product price is not affected (e.g. steak doeness).
`note`	`string`	false	The optional attribute-related comment, provided by customer.

### Payment The product payment information.

Name Type Required Description

isSettled boolean true true, if payment has already been completed (e.g. transaction has been transferred), false otherwise.

method

string (please see allowed values)

false

One of following: cash, card

The description of payment method that was used (when isSettledis true) or will be used (when isSettled is false).

## Configuration To communicate with external system properly, the external system administrators must provide values stated below to the venue owners or PORTOS support. | Value | Type | Description | | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Value | Type | Description | | External system unprocessed orders URL | `string` | The URL hosted by external system, that will be requested by PORTOS to fetch the unprocessed orders. | | External system process order URL | `string` | The URL hosted by external system, that will be requested by PORTOS to process (confirm or reject) order. | | API key | `string` | The venue-specific API key (authorization token) that will be placed in the `key` query parameter of all HTTP requests. | | Fetch period | `int` | The period (in seconds) that specifies, how often will PORTOS system invoke the "fetch unprocessed orders" API call. Default value is `15`seconds. | ## Example In all request examples below, we will assume following configuration: * external system unprocessed orders URL: `https://the-foo-bar.sk/unprocessed_orders` * external system process order URL: `https://the-foo-bar.sk/process_order` * API key is: `my-token` ### Step 1: Fetching unprocessed orders The PORTOS will request following URL: ```javascript GET https://the-foo-bar.sk/unprocessed_orders?version=1&key=my-token ``` The external system returns following payload as an response: ```javascript [ { "externalId": "b478396ad654", "type": "delivery", "delivery": { "address": { "line1": "Kresankova 12", "line2": "", "city": "Bratislava", "zipCode": 84105, "note": "Please knock twice" }, "fee": 1.99 }, "createdAt": "2021-02-01T12:01:00.000Z", "scheduledAt": null, "customer": { "name": "John Doe", "phone": "+421 900 123 456", "email": "john.doe@example.com" }, "products": [ { "id": "1234", "name": "Burger", "quantity": 1, "baseUnitPrice": 8.99, "note": "", "additions": [ { "id": "11002", "name": "No cheese", "quantity": 1, "unitPrice": 0.00, "note": "" }, { "id": "11002", "name": "Extra bacon", "quantity": 1, "unitPrice": 1.99, "note": "" } ] } ], "currency": "EUR", "payment": { "isSettled": true, "method": "card" }, "wrappingFee": 0, "tip": 0, "totalPrice": 12.97, "note": null }, { "externalId": "6a2ad048e32d", "type": "takeAway", "delivery": null, "createdAt": "2021-02-01T12:01:00.000Z", "scheduledAt": "2021-02-01T13:00:00.000Z", "customer": { "name": "John Doe", "phone": "+421 900 123 456", "email": "john.doe@example.com" }, "products": [ { "id": "2345", "name": "Fries", "quantity": 2, "baseUnitPrice": 4.99, "note": "", "additions": [ { "id": "11024", "name": "Ketchup", "quantity": 1, "unitPrice": 1.99, "note": "" } ] } ], "currency": "EUR", "payment": { "isSettled": false, "method": null }, "wrappingFee": 0, "packagingDeposit": 0, "tip": 0, "totalPrice": 13.96, "note": null } ] ``` As we can see, the external systems returns two unprocessed orders. ### Step 2: Order acceptation The PORTOS will mark first order as accepted by requesting following URL: ```javascript POST https://the-foo-bar.sk/process_order?version=1&key=my-token&externalId=b478396ad654&status=accepted&estimatedCompletionAt=2021-02-01T13%3A01%3A00.000Z ``` {% hint style="info" %} Please note that all query parameters are URL encoded. In URL above, the `estimatedCompletionAt` query parameter value `2021-02-01T13:01:00.000Z` is URL encoded as `2021-02-01T13%3A01%3A00.000Z`. {% endhint %} ### Step 3: Fetching unprocessed orders The PORTOS will request unprocessed requests again: ```javascript GET https://the-foo-bar.sk/unprocessed_orders?version=1&key=my-token ``` The external system returns following payload as an response: ```javascript [ { "externalId": "6a2ad048e32d", "type": "takeAway", "delivery": null, "createdAt": "2021-02-01T12:01:00.000Z", "scheduledAt": "2021-02-01T13:00:00.000Z", "customer": { "name": "John Doe", "phone": "+421 900 123 456", "email": "john.doe@example.com" }, "products": [ { "id": "2345", "name": "Fries", "quantity": 2, "baseUnitPrice": 4.99, "note": "", "additions": [ { "id": "11024", "name": "Ketchup", "quantity": 1, "unitPrice": 1.99, "note": "" } ] } ], "currency": "EUR", "payment": { "isSettled": false, "method": null }, "wrappingFee": 0, "packagingDeposit": 0, "tip": 0, "totalPrice": 13.96, "note": null } ] ``` The recently accepted order no longer appears in unprocessed orders collection. ### Step 4: Order rejection The PORTOS will mark remaining order as rejected by requesting following URL: ```javascript POST https://the-foo-bar.sk/process_order?version=1&key=my-token&externalId=6a2ad048e32d&status=rejected&rejectionReason=The%20food%20is%20out%20of%20stock. ``` {% hint style="info" %} Please note that all query parameters are URL encoded. In URL above, the `rejectionReason` query parameter value `The food is out of stock.` is URL encoded as `The%20food%20is%20out%20of%20stock.`. {% endhint %} ### Step 5: Fetching unprocessed orders The PORTOS will request unprocessed requests again: ```javascript GET https://the-foo-bar.sk/unprocessed_orders?version=1&key=my-token ``` All requests has been processed (rejected or accepted). The external system returns empty collection as an response. ```javascript [] ``` ## Changelog ### Version 1.4 (2024-02-05) * Added support for [products](#product) with negative `baseUnitPrice` as well for [product additions](#productaddition) with negative `unitPrice`. * Requires PORTOS Pokladňa version 4.1.13 or later. ### Version 1.3 (2022-12-07) * New `packagingDeposit` field added. * Supported in PORTOS Pokladňa version 4.0.25 or later. * Supported in PORTOS Online Objednávky version 3.3.8 or later. ### Version 1.2 (2022-08-12) * New `tip` field added. * Supported in PORTOS Pokladňa version 4.0.9 or later. ### Version 1.1 (2022-03-17) * New `note` field added. * Supported in PORTOS Online Objednávky version 1.0.15 or later. ### Version 1.0 * Initial version # Rewards API Rewards connector that enables to provide vouchers, coupons, rewards or deals for your customers. ## Glossary | Term | Definition | | --------------- | --------------------------------------------------------------------------------------------------------- | | PORTOS | The cash register solution developed by Nine Digit, s.r.o. | | External system | The 3rd party system (such as e-shop or food delivery platform) from which rewards are fetched to PORTOS. | | Venue | E.g. store or restaurant. | | Cashier | The Venue personnel. | | Customer | Person who purchases the goods. | | Reward | The coupon or discount that customer can be rewarded with. | | Product | The product that is being purchased by customer. | ## How it works The *Rewards API* is a mechanism that allows importing rewards (such as coupons, deals or discounts) to the PORTOS system. The PORTOS system acts as an "client" initiating HTTP request targeting the *external system*, that acts as an "server" and handles the following requests: 1. Fetch available rewards 2. Claim reward(s) The PORTOS system expects that responses from *external system* follows data format described below. ## Fetch available rewards `GET` `{external-system}{get-rewards-url}` The PORTOS system will fetch available rewards from the external system, by initiating GET HTTP request to the external system address. External system returns response of type [`CustomerRewards`](#customerrewards), that contains the collection of rewards, that customer can be rewarded with. ### Query Parameters | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------- | | version\* | string | The version of the exchange protocol. For versions 1.X, value is set to `1`. | | key\* | string | The API key. | | customerId | string | The customer identifier. E.g. the serial number of the loyalty card, if provided by customer. | ### Headers | Name | Type | Description | | --------------- | ------ | ------------------------------------------------------------------------------------- | | Accept-Language | string | Specifies the desired localization for receiving messages from the API. E.g. `sk-SK`. | {% tabs %} {% tab title="200 " %} {% code overflow="wrap" %} ```json { "customer": { "displayName": "John Doe", "email": "example@portos.sk", "points": 1281 }, "maxApplicableRewards": null, "rewards": [ { "id": "dda658c8-7ca1-4993-9212-f1bcd992e638", "title": "Najlacnejšia pizza za jeden cent!", "description": "Získajte najlacnejšiu pizzu za jeden cent. Zľava platí pri nákupe nad 20 eur.", "conditions": [ { "purchase": { "minAmountIncludingVat": 20 } } ], "items": [ { "target": "purchaseItem", "discountType": "absolute", "discountAmount": 0.01, "purchaseItemLookupMode": "cheapest", "purchaseItemFilter": { "articleCategoryLabels": [ "PIZ" ], "maxQuantity": 1 } } ] }, { "id": "0214d09d-844f-4677-a449-829ddbf5d1cc", "title": "Vymeňte 1000 bodov za 5 eurovú zľavu", "items": [ { "target": "purchase", "discountType": "absolute", "discountAmount": 5 } ], "priceInPoints": 1000 } ] } ``` {% endcode %} {% endtab %} {% tab title="401 The bearer authorization token is invalid." %} {% code overflow="wrap" %} ```json { "message": "This is the optional message describing the error." } ``` {% endcode %} {% endtab %} {% tab title="403 The orders cannot be fetched. The reason may be provided in body." %} {% code overflow="wrap" %} ```json { "message": "A loyalty card is required for receiving rewards.", "code": "CUSTOMER_ID_REQUIRED" } ``` {% endcode %} {% endtab %} {% endtabs %} ## Claim reward(s) `POST` `{external-system}{claim-rewards-url}` After the reward is confirmed by Cashier trough the PORTOS cash register system user interface, the PORTOS system will initiate the POST HTTP request to the external system, to mark reward(s) as claimed. ### Query Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ---------------------------------------------------------------------------- | | version\* | string | The version of the exchange protocol. For versions 1.X, value is set to `1`. | | key\* | string | The API key. | ### Headers | Name | Type | Description | | --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Accept-Language | string | Specifies the desired localization for receiving messages from the API. E.g. `sk-SK`. | | Idempotency-Key | string | Optional. A unique key identifying this claim attempt (e.g. a UUID). If a claim with the same key has already been processed, the server returns the original response without applying the claim again, so the request is safe to retry. Reuse the same key only when retrying the exact same claim; reusing a key with a different set of `rewardIds` is rejected with HTTP `422`. Requests without this header are processed normally (non-idempotent). | ### Request Body | Name | Type | Description | | ------------------------------------------- | --------- | --------------------------------------------------- | | rewardIds\* | string\[] | Non-empty collection of claimed reward identifiers. | {% tabs %} {% tab title="200 The reward usage has been acknowledged by the external system." %} {% code overflow="wrap" %} ```json /* No response body is required by PORTOS. */ ``` {% endcode %} {% endtab %} {% tab title="401 The bearer authorization token is invalid." %} ```json { "message": "This is the optional message describing the error." } ``` {% endtab %} {% tab title="403 Error when marking reward as used. E.g. reward has already been used." %} ```json { "message": "This reward is currently not available.", "code": "REWARD_USAGE_LIMIT_EXCEEDED", "rewardId": "29e61e3b-34ae-4c1f-9bd8-f4ef9925a1f8" } ``` {% endtab %} {% tab title="422 Unprocessable Entity" %} The `Idempotency-Key` was already used with a different claim request. {% endtab %} {% endtabs %} ### Idempotency The Portos POS application may retry a claim request whose response it did not receive. For example after a network timeout, when it cannot tell whether the original request was processed. To let it do so safely, the client can attach an **`Idempotency-Key`** header (see *Headers*) that uniquely identifies a single claim attempt. Supporting idempotency is **optional but recommended**: without it, a retried claim is processed a second time and the customer's rewards may be claimed twice. #### Expected server behaviour When a claim request carries an `Idempotency-Key`, the server should: 1. **Look the key up**, scoped to the API key it was authenticated with. Keys from different API keys are independent and must never collide. 2. **First time the key is seen:** process the claim normally and **store the resulting response** (both the HTTP status and the body) together with the key. 3. **Key seen again with the same request:** return the **stored response** and do **not** apply the claim again. The response must be identical to the original (same status and body). 4. **Key seen again with a different request** (a different set of `rewardIds`): reject it with **`422 Unprocessable Entity`**. This signals that the key was reused incorrectly and protects against accidental key collisions. Only **completed** requests should be stored. If the claim cannot be completed (e.g. the server returns `5xx` or the request never finishes) the key must **not** be recorded, so that a later retry is processed rather than replaying an outcome that never happened. #### Retention Stored keys should be retained for a bounded period; **24 hours** is sufficient, as the client only retries within a short window of the original attempt. Keys may be discarded after that. ## Configuration To communicate with external system properly, the external system administrators must provide values stated below to the venue owners or PORTOS support. | Value | Type | Description | | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | External system "get rewards" URL | `string` | The URL hosted by external system, that will be requested by PORTOS to fetch rewards. | | External system "claim rewards" URL | `string` | The URL hosted by external system, that will be requested by PORTOS to claim rewards. | | API key | `string` | The venue-specific API key (authorization token) that will be placed in the `key` query parameter of all HTTP requests. | ## Data model The rewards API data model is described below. {% hint style="info" %} All prices include taxes. {% endhint %} ### CustomerRewards The collection of rewards available for given customer.

Name	Type	Required	Description
`rewards`	`Reward[]`	true	The collection of available rewards.
customer	`Customer`	false	The information about customer, if available.
`maxApplicableRewards`	`int`	false	The maximum number of applicable rewards per given purchase.

### Customer Information about customer.

Name	Type	Required	Description
`displayName`	`string`	true	The display name of customer or customer loyalty account.
`points`	`number`	true	Represents number of loyalty points associated with customer account.
`firstName`	`string`	false	First name.
`lastName`	`string`	false	Last name.
`email`	`string`	false	E-mail address that can be used when sending receipt in e-mail form.
`maxApplicableRewards`	`int`	false	The maximum number of rewards that can be applied per purchase. The rewards can also be limited by specifying available customers loyalty points and price in points of reward.

### Reward Represents the reward.

Name	Type	Required	Description
`id`	`string`	true	Unique reward identifier.
`title`	`string`	true	Reward title.
`description`	`string`	false	Short reward description.
`conditions`	`RewardCondition[]`	false	Conditions that need to be fulfilled in order for the customer to claim the reward.
`items`	`RewardItem[]`	true	Collection of one or more items associated with given reward.
`activationDate`	`string`	false	If specified, the reward becomes applicable only after the specified date and time in ISO_8601 format, expressed in UTC.
`expirationDate`	`string`	false	If specified, the reward is applicable only before the specified date and time in ISO_8601 format, expressed in UTC.
`minPurchaseAmountIncludingVat`	`number`	false	If specified, represents the minimum purchase amount required to claim the reward.
`priceInPoints`	`number`	false	Specifies number of loyalty points subtracted from customer's loyalty account once the reward is claimed.
`remainingUsage`	`number`	false	Specifies maximum number of times can this reward be claimed by any customer.
`remainingCustomerUsage`	`number`	false	Specifies maximum number of times can this reward be claimed by given customer.

### RewardCondition

Name	Type	Required	Description
`purchase`	`RewardPurchaseCondition`	false	Optional conditions related to purchase.

### RewardPurchaseCondition

Name	Type	Required	Description
`minAmountIncludingVat`	`number`	false	If specified, represents the minimum purchase amount required to claim the reward.

### RewardItem Single reward item.

Name	Type	Required	Description
`target`	`string`	true	One of `RewardItemTarget`.
`productFilter`	`RewardItemProductFilter`	false	Required, when `target` is `product`. Must be null otherwise.
`purchaseItemFilter`	`RewardItemPurchaseItemFilter`	false	Required, when `target` is `purchaseItem`. Must be null otherwise.
`purchaseItemLookupMode`	`string`	false	One of `PurchaseItemLookupMode.` when `target` is `purchaseItem`. Must be null otherwise.
`discountType`	`string`	true	One of `RewardItemDiscountType`. If `target` is equal to `purchase`, value must be `prcentage` or `absolute`.
`discountAmount`	`number`	false	Positive, non-zero number. Minimal value is `0.01`. Required, when `discountType` is `absolute` or `relative`. Must be null otherwise.
`discountRate`	`number`	false	Positive, non-zero number, with value between `0.01` and `100`. Required, when `discountType` is `percentage`. Must be null otherwise.

### RewardItemDiscountType List of known discount types:

Name	Description
`percentage`	Reward provides a percentage discount.
`absolute`	Reward provides a discount that is specified by a fixed or absolute value rather than a percentage.
`relative`	Reward provides a discount by subtracting a specific value from the original retail price of a product or service.

### RewardItemTarget The target that reward item applies to.

Name	Description
`purchaseItem`	Reward provides a discount to single purchase item. Purchase item can be specified by `RewardItemPurchaseItemFilter`. If no suitable product is found in the purchase, reward is not applied.
`product`	Reward provides a discount for a certain product, specified by `RewardItemProductFilter`. If given product is not initially included in the purchase, it will be added to the purchase automatically, so that the discount can be applied.
`purchase`	Reward applies a discount to entire purchase

### RewardItemProductFilter Model that uniquely identifies product.

Name	Type	Required	Description
`pluId`	`PluId`	false	At least one of identifier fields (`pluId` or `id`) must be specified.
`id`	`string`	false	At least one of identifier fields (`pluId` or `id`) must be specified.

### RewardItemPurchaseItemFilter Model that selects purchase item.

Name	Type	Required	Description
`pluIds`	`PluId[]`	false	`TicketItem.Plu.Code` and `TicketItem.Plu.StockName`must be equal to one of provided values, if value is not null or empty.
`articleCategoryLabels`	`string[]`	false	`TicketItem.Plu.ArticleCategoryLabel` must be equal to one of provided values, if value is not null or empty.
`minUnitPriceIncludingVat`	`number`	false	If specified, `TicketItem.UnitPriceIncludingVat` must be greater than or equal to provided value.
`maxUnitPriceIncludingVat`	`number`	false	If specified, `TicketItem.UnitPriceIncludingVat` must be less than or equal to provided value.
`minQuantity`	`number`	false	If specified, `TicketItem.Quantity` must be greater than or equal to provided value.
`maxQuantity`	`number`	false	If specified, `TicketItem.Quantity` must be less than or equal to provided value.

### PurchaseItemLookupMode Specifies, what strategy is used to look up single purchase item among all items in purchase, that reward will be applied to.

Name	Description
`cheapest`	Prefers least expensive product, based on it's unit price.
`mostExpensive`	Prefers most expensive product, based on it's unit price.

## Error models ### Error Error model received for non-2XX HTTP statuses.

Name	Type	Required	Description
`message`	`string`	true	Human readable message describing the error.
`rewardId`	`string`	false	Id of `Reward`, if error is reward-specific.
`code`	`string`	false	Available, if error matches one of known error codes.

### ErrorCode The third-party server can return an [`Error`](#error) with one of the following codes:

Error code	Description
`CUSTOMER_ID_REQUIRED`	Should be used when PORTOS attempts to fetch rewards without providing loyalty card id, but loyalty card is required by the third-party server.
`UNKNOWN_CUSTOMER_ID`	Customer loyalty card is not recognized.
`REWARD_NOT_FOUND`	Reward is not found.
`REWARD_NOT_AVAILABLE`	Reward is currently not available. E.g. current date and time does not match with `Rewards` `ActivationDate` and `ExpirationDate`.
`REWARD_USAGE_LIMIT_EXCEEDED`	The reward usage limit has been exceeded.
`REWARD_CUSTOMER_USAGE_LIMIT_EXCEEDED`	The reward usage limit has been exceeded for the specified customer.
`INSSUFICIENT_LOYALTY_POINTS`	The customer lacks sufficient loyalty points to claim the reward.

## Versioning This API uses [semantic versioning](https://semver.org/). 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.0 (2026-07-17) Added: * Optional idempotency for the claim route through the `Idempotency-Key` request header, so a client can safely retry a claim whose response was lost without claiming the rewards twice. The header is optional and backward compatible. Existing integrations are unaffected. Changed: * The protocol has been declared stable. ### Version 1.0-beta.2 (2023-05-29) * Added: * Accept-Language header added to HTTP requests. * Changed: * `RewardRule` renamed to `RewardCondition`. ### Version 1.0-beta.1 (2023-05-26) * Initial version. # PDA Files Minimal approach integration using text files ## Introduction {% tabs %} {% tab title="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. {% endtab %} {% tab title="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. {% endtab %} {% endtabs %} ## 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`). {% hint style="info" %} When contacting technical support, please attach the log file as well. {% endhint %} ## 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)](#ticket-item-line) | Yes, at least one | | `D` | [Footer text](#footer-text-line) | No | | `F` | [Fiscal name](#fiscal-name-line) | No | | `L` | [Ticket location](#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 ``` {% file src="/files/prEf1X9is0miOkFZ1I7r" %} ## Versioning This API uses [semantic versioning](https://semver.org/). 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. # Migration to V4.3 Thi article describes breaking changes between PORTOS API v4.2 and v4.3. ## DailySalesReportFiscalInfo * `tipTicketItemsCount` property has been added. * `tipTicketItemsAmountIncludingVat` property has been added. ## NonfiscalRecordContext * `contentFlags` property has been added. Please refer to the [Data Models article](/data-models#nonfiscalrecordcontext) for more information on how to use this property when invoking non-fiscal printing. ## PaymentTypeCategory * New enumeration value `qrPayment` has been added. ## TicketItem * `TicketItemType`: New enum value `Tip` is added. # Migration to V4.2 Thi article describes breaking changes between PORTOS API v4.1 and v4.2. ## TicketItem * `SubItems`: New optional collection of [TicketSubItem](/data-models#ticketsubitem) added. # Migration to V4.1 Thi article describes breaking changes between PORTOS API v4.0 and v4.1. ## Plu * **`RetailPrice`**: Property has been renamed to `RetailPriceIncludingVat`. As the name suggests, the retail price includes VAT now. * `VatCategory`: The maximum value is changed from 5 to 10. ## PluPriceHistoryItem * `RetailPrice`: Property has been renamed to `RetailPriceIncludingVat`. As the name suggests, the retail price includes VAT now. ## PluPurchaseType * `VatCategory`: The maximum value is changed from 5 to 10. ## Vat * `Category`: The maximum value is changed from 5 to 10. * `Rate`: Data type is changed from decimal to nullable decimal, so value can be `null`as well. * **`PlannedRateChange`**: New property `PlannedRateChange` of type `VatRateChange` has been added. * **`LastModifiedAt`**: Date and time of last update. Enforced by API. ## VatIncome * **`VatCategory`**: Property has been removed. * `VatRate`: Data type is changed from decimal to nullable decimal, so value can be `null`as well. ## VatInfo * `Category`: The maximum value is changed from 5 to 10. * `Rate`: Data type is changed from decimal to nullable decimal, so value can be `null`as well. # Migration to V4 Thi article describes breaking changes between PORTOS API v3.X and v4.0. ## Authorization result ### TokenId property `AccessToken` has been renamed to `TokenId` in [authorization result](/authentication/authentication-schemes/jwt-bearer-authentication). ## Article category ### SortHint `SortHint` property has been added to achieve user defined article categories sorting in cash register application. This optional property is of nullable integer type. Article categories with lowest value are displayed first, `null` have lowest priority. Categories with same `SortHint` value are sorted alphabetically. Example:

SortHint	Description
0	Beers
0	Drinks
1	Pizza
2	Wine
null	Beverages
null	Specials

### Tags New optional `string` collection property that helps to associate user-defined tags with article category. Based on tags collection, new reports are available in statistics in both PORTOS CashRegister (Pokladňa) and PORTOS BackOffice applications. ## Customer The customer resource has has undergone many improvements, e.g. each customer account can now be associated with multiple cards. Please see table below for more information. | Name (v3) | Name (v4) | Note | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | - | `ActivationTime` | New property that specifies date and time, from which customer account can be associated with `Ticket`. | | `Address` | `Address` | Object properties has been changed. `ZipCode` has been renamed to `PotalCode`. New `Coordinates` property has been added (object with `Longitude` and `Latitude` properties). New `Note` property has been added (optional `string` property to store additional information related to address). | | - | `BirthDate` | Optional customer birth date. | | `CardId` | - | This property has been removed. Card identifier is moved to `SerialNumber` property of element in `Cards` collection. | | - | `Cards` | Collection of cards associated with this customer. | | - | `Company` | New property that aggregates company-related information. Properties: `Name`, `CRN`, `VatId`, `TaxId`. | | `Contact` | - | This property has been removed. `Fax` and `Mobile` properties has been removed (values are available in `Meta` object after migration). `Phone` and `Email` values are moved to root object (`Customer.Phone` and `Customer.Email`). | | | `CreditTransactions` | Collection of transactions that affects `Credit` property. | | `CRN` | - | Moved to `Customer.Company.CRN`. | | - | `DeliveryAddress` | New optional delivery address property of type `CustomerAddress`. | | `ExpirationDate` | `ExpirationTime` | Renamed. | | - | `ExternalId` | Optional unique identifier supplied by external system. | | - | `FirstName` | Optional customer first (given) name. | | | `Gender` | Optional gender. One of folowing: `Male`, `Female` or `null` (for unknown or other). | | - | `Id` | New unique identifier (in v3, `CardId` has been used as unique identifier). | | - | `IsCompany` | Boolean value that specifies whether this customer represents company. | | | `LastName` | Optional customer last (family) name. | | `Name` | `FullName` | Renamed. | | - | `Note` | Optional note related to customer. | | - | `Meta` | Object that hold any additional data (may be supplied by external system). | | - | `Status` | New overall status of customer card. Value is one of following: `Valid`, `NotYetValid`, `Expired`. | | `TaxId` | - | Moved to `Customer.Company.TaxId`. | | `VatId` | - | Moved to `Customer.Company.VatId`. | ## Plu | Name (v3) | Name (v4) | Note | | ------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `LastPurchasePrice` | `LastPurchasePrice` | Now stored as price excluding VAT (in previous version, this property included VAT). | | `RetailPrice` | `RetailPrice` | Now stored as price excluding VAT (in previous version, this property included VAT). | | `StockValue` | `StockValue` | Now stored as price excluding VAT (in previous version, this property included VAT). | | `Type` | `Type` | Range of allowed values has been reduced to `StockItem`, `Recipe` and `Service`. Removed types (`Credit` and `Discount`) are migrated to `Service`. | | - | `SpecialRegulation` | Optional property that describes reason to associate given product with 0% VAT rate. This property has been added to comply with eKasa legislation. | | - | `IsCashbackAllowed` | Determines whether the sale of this product will generate cashback to the customer. | | - | `IsFavorite` | Boolean property to easier product lookup in cash register application. | | - | `SortHint` | Same sorting rules as `ArticleCategory.SortHint` are applied. | ## Ticket Serveral new properties were added to `Ticket` model. No properties were removed nor renamed. | Name (v4) | Note | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CloseDate` | Formerly located in `CloseInfo.CloseDate`. | | `ExternalId` | Optional identifier supplied by external system. | | `InvoiceNumber` | Invoice number. Has value only when `Type` is `Invoice`. | | `IsParagon` | Specifies whether this ticket represents paragon. | | `IssueDate` | Date of issue. May be different from `OpenDate`, when paragon receipt is registered. | | `ParagonNumber` | Paragon sequence number. Has value only when `IsParagon` is `true`. | | `State` | Specifies ticket status. Allowed values: `Open`, `Closed` (receipt has been printed for given ticket) | | `Type` | Specifies ticket type. Allowed values: `CashRegister`, `Invalid`, `Invoice`. Invalid receipts are used in training mode. Invoice is ticket without `Items` collection. | ## TicketCloseInfo `CloseInfo` property of `Ticket`. | Name (v3) | Name (v4) | Note | | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | CloseDate | - | Property has been removed in favor of `Ticket.CloseDate`. | | - | `EKasa` | Contains properties related to eKasa legislation. Properties: `TicketId`, `TicketIsOnline`, `TicketForm` and `TicketFormOptions`. | ## TicketItem | Name (v3) | Name (v4) | Note | | ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | - | `ExternalId` | Optional identifier supplied by external system. | | - | `Type` | Type of ticket item. Allowed values: `Positive`, `ReturnedContainer`, `Returned`, `Correction`, `Discount`, `Advance`, `Voucher` and `Credit`. | | `UnitPriceBrutto` | `UnitPrice` | Property has been renamed and value now contains unit price excluding VAT. | | - | `ReferenceFiscalTicketId` | Reference to ticket identifier, which can be found in `Ticket.CloseInfo.EKasa.TicketId`. Required for `TicketItem` with `Type` equal to `Correction` or `Returned`. | | - | `VoucherNumber` | Voucher number. Specified only when `Type` is `Voucher`. | | - | `IsQuantityFixed` | Specifies whether Quantity cannot be changed. | | - | `CourseNumber` | Formerly located in `TicketItem.Plu.CourseNumber`. | ## TicketItemPlu | Name (v3) | Name (v4) | Note | | -------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `CourseNumber` | - | Property was moved up, to `TicketItem` model. | | - | `IsCashbackAllowed` | Determines whether the sale of this product will generate cashback to the customer. | | - | `SpecialRegulation` | Optional property that describes reason to associate given product with 0% VAT rate. This property has been added to comply with eKasa legislation. | | `Type` | `Type` | Range of allowed values has been reduced to `StockItem`, `Recipe` and `Service`. Removed types (`Credit` and `Discount`) are migrated to `Service`. | # Legacy documentation To view documentation for PORTOS version 2.X and older (formerly known as *mPOS* Cash Register system), please see the legacy documentation at .