NAV Navbar
Logo
shell

Introduction

Welcome to the CassaNova APIs! You can use our APIs to integrate your system with CassaNova infrastructure.

Authentication

Using OAuth 2.0 to Access CassaNova APIs

CassaNova APIs use the OAuth 2.0 protocol for authentication and authorization. CassaNova supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications.

To begin, obtain OAuth 2.0 client credentials from the CassaNova API Console. Then your client application requests an access token from the CassaNova Authorization Server, extracts a token from the response, and sends the token to the CassaNova API that you want to access

Basic steps

All applications follow a basic pattern when accessing a CassaNova API using OAuth 2.0. At a high level, you follow four steps:

1. Obtain OAuth 2.0 credentials from the CassaNova API Console.

Visit the CassaNova API Console to obtain OAuth 2.0 credentials such as a client ID and client secret that are known to both CassaNova and your application. The set of values varies based on what type of application you are building. For example, a JavaScript application does not require a secret, but a web server application does.

2. Obtain an access token from the CassaNova Authorization Server.

Before your application can access private data using a CassaNova API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect to CassaNova, while an application installed on a device that has no browser uses web service requests.

Some requests require an authentication step where the user logs in with their CassaNova account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent.

If the user grants the permission, the CassaNova Authorization Server sends your application an access token (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error.

It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front.

3. Send the access token to an API.

After an application obtains an access token, it sends the token to a CassaNova API in an HTTP authorization header.

Access tokens are valid only for the set of operations and resources described in the scope of the token request.

4. Refresh the access token, if necessary.

Access tokens have limited lifetimes. If your application needs access to a CassaNova API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

Using OAuth 2.0 for Web Server Applications

Using OAuth 2.0 for Web Server Applications

This document explains how web server applications use CassaNova OAuth 2.0 endpoints to implement OAuth 2.0 authorization to access CassaNova APIs. OAuth 2.0 allows users to share specific data with an application while keeping their usernames, passwords, and other information private.

This OAuth 2.0 flow is specifically for user authorization. It is designed for applications that can store confidential information and maintain state. A properly authorized web server application can access an API while the user interacts with the application or after the user has left the application.

Obtaining OAuth 2.0 access tokens

The following steps show how your application interacts with CassaNova’s OAuth 2.0 server to obtain a user’s consent to perform an API request on the user’s behalf. Your application must have that consent before it can execute a CassaNova API request that requires user authorization.

Step 1: Authorization

An example URL is shown below, with line breaks and spaces for readability.

https://api.cassanova.com/oauth/authorize?
 scope=read_department&
 state=state_parameter_passthrough_value&
 redirect_uri=http://myapp.com/redirect
 response_type=code&
 client_id=client_id

When your application needs to access a user’s data, redirect the user to CassaNova’s OAuth 2.0 server.

Generate a URL to request access from CassaNova’s OAuth 2.0 endpoint at https://api.cassanova/oauth/authorize. This endpoint is accessible over HTTPS; plain HTTP connections are refused.

Parameter Description
client_id Required. The client ID for your application. You can find this value in the API Console.
redirect_uri Required. Determines where the API server redirects the user after the user completes the authorization flow. The value must exactly match one of the redirect_uri values listed for your project in the API Console. Note that the http or https scheme, case, and trailing slash (‘/’) must all match.
response_type Required. Determines whether the CassaNova OAuth 2.0 endpoint returns an authorization code. Set the parameter value to code for web server applications.
scope Required. A comma-delimited list of scopes that identify the resources that your application could access on the user’s behalf. These values inform the consent screen that CassaNova displays to the user.
state Recommended. Specifies any string value that your application uses to maintain state between your authorization request and the authorization server’s response. The server returns the exact value that you send as a name=value pair in the hash (#) fragment of the redirect_uri after the user consents to or denies your application’s access request.

Step 2: CassaNova prompts user for consent In this step, the user decides whether to grant your application the requested access. At this stage, CassaNova displays a consent window that shows the name of your application and the CassaNova API services that it is requesting permission to access with the user’s authorization credentials. The user can then consent or refuse to grant access to your application.

Your application doesn’t need to do anything at this stage as it waits for the response from CassaNova’s OAuth 2.0 server indicating whether the access was granted. That response is explained in the following step.

Step 3: Handle the OAuth 2.0 server response

The OAuth 2.0 server responds to your application’s access request by using the URL specified in the request.

If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. The authorization code or error message that is returned to the web server appears on the query string, as shown below:

An error response:

https://myapp.com/redirect?error=access_denied

An authorization code response:

https://myapp.com/redirect?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Step 4: Exchange authorization code for refresh and access tokens

The following snippet shows a sample request:

curl -X POST "https://api.cassanova.com/oauth/token"
    -H "Content-Type:application/x-www-form-urlencoded"
    -H "X-Requested-With:*"
    -d "code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
        client_id=your_client_id&
        client_secret=your_client_secret&
        redirect_uri=https://myapp.com/redirect&
        grant_type=authorization_code"
The following snippet shows a sample response:
{
  "access_token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI5MiIsImlzcyI6ImNsaWVudDoxMjM0NTY3ODkwIiwiZXhwIjoxNDk1MTkyNDc3LCJzY29wZSI6IndyaXRlX2RlcGFydG1lbnQsY2lhb19kZXBhcnRtZW50LHJlYWRfZGVwYXJ0bWVudCJ9.12SP1CxlOriw0BN7d7IfodSDMKa1umEGoX9IHiHzw3klfBvsFom2WnI3cEtBKDrAMfSAvJ0zgTbGzDuK3JzGMw",
  "expires_in":3600,
  "token_type":"Bearer",
  "refresh_token":"35bf9322-ccf5-4d42-9dfd-67584d76f46b"
}

After the web server receives the authorization code, it can exchange the authorization code for an access token.

To exchange an authorization code for an access token, call the https://api.cassanova.com/oauth/token endpoint and set the following parameters:

Parameter Description
code The authorization code returned from the initial request.
client_id The client ID obtained from the API Console.
client_secret The client secret obtained from the API Console.
redirect_uri One of the redirect URIs listed for your project in the API Console.
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code.

CassaNova responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

The response contains the following fields:

Parameter Description
access_token The token that your application sends to authorize a CassaNova API request.
refresh_token A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access.
expires_in The remaining lifetime of the access token in seconds.
token_type The type of token returned. At this time, this field’s value is always set to Bearer.

OAuth 2.0 for Mobile & Web Apps

This document explains how applications installed on devices like phones, tablets, and computers use CassaNova’s OAuth 2.0 endpoints to authorize access to CassaNova APIs. OAuth 2.0 allows users to share specific data with an application while keeping their usernames, passwords, and other information private.

Obtaining OAuth 2.0 access tokens

The following steps show how your application interacts with CassaNova’s OAuth 2.0 server to obtain a user’s consent to perform an API request on the user’s behalf. Your application must have that consent before it can execute a CassaNova API request that requires user authorization.

Step 1: Generate a code verifier and challenge

CassaNova supports the Proof Key for Code Exchange protocol to make the installed app flow more secure. A unique code verifier is created for every authorization request, and its transformed value, called “code_challenge”, is sent to the authorization server to obtain the authorization code.

Create the code verifier

A code_verifier is a high-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / “-” / “.” / “_” / “~”, with a minimum length of 43 characters and a maximum length of 128 characters.

The code verifier should have enough entropy to make it impractical to guess the value.

Create the code challenge

Two methods of creating the code challenge are supported.

Code Challenge Generation Methods
plain The code challenge is the same value as the code verifier generated above. code_challenge = code_verifier
S256 The code challenge is the Base64URL (with no padding) encoded SHA256 hash of the code verifier. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Step 2: Authorization

To obtain user authorization, send a request to CassaNova’s authorization server at https://api.cassanova.com/oauth/authorize. This endpoint handles active session lookup, authenticates the user, and obtains user consent. The endpoint is only accessible over SSL, and it refuses HTTP (non-SSL) connections.

The authorization server supports the following query string parameters for installed applications:

Parameter Description
client_id Required. The client ID for your application. You can find this value in the API Console.
redirect_uri Required. Determines where the API server redirects the user after the user completes the authorization flow. The value must exactly match one of the redirect_uri values listed for your project in the API Console. Note that the http or https scheme, case, and trailing slash (‘/’) must all match.
response_type Required. Determines whether the CassaNova OAuth 2.0 endpoint returns an authorization code. Set the parameter value to code for web server applications.
scope Required. A comma-delimited list of scopes that identify the resources that your application could access on the user’s behalf. These values inform the consent screen that CassaNova displays to the user.
state Recommended. Specifies any string value that your application uses to maintain state between your authorization request and the authorization server’s response. The server returns the exact value that you send as a name=value pair in the hash (#) fragment of the redirect_uri after the user consents to or denies your application’s access request.
code_challenge_method Recommended. Specifies what method was used to encode a code_verifier that will be used during authorization code exchange. This parameter must be used with the code_challenge parameter. The value of the code_challenge_method defaults to “plain” if not present in the request that includes a code_challenge. The only supported values for this parameter are “S256” or “plain”.
code_challenge Recommended. Specifies an encoded code_verifier that will be used as a server-side challenge during authorization code exchange. This parameter must be used with the code_challenge parameter described above. See create code challenge section above for more information.

Step 3: Cassanova prompts user for consent

In this step, the user decides whether to grant your application the requested access. At this stage, CassaNova displays a consent window that shows the name of your application and the CassaNova API services that it is requesting permission to access with the user’s authorization credentials. The user can then consent or refuse to grant access to your application.

Your application doesn’t need to do anything at this stage as it waits for the response from CassaNova’s OAuth 2.0 server indicating whether the access was granted. That response is explained in the following step.

Step 4: Handle the OAuth 2.0 server response

The OAuth 2.0 server responds to your application’s access request by using the URL specified in the request.

If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. The authorization code or error message that is returned to the web server appears on the query string, as shown below:

An error response:

https://myapp.com/redirect?error=access_denied

An authorization code response:

https://myapp.com/redirect?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Step 5: Exchange authorization code for refresh and access tokens

The following snippet shows a sample request:

curl -X POST "https://api.cassanova.com/oauth/token"
    -H "Content-Type:application/x-www-form-urlencoded"
    -H "X-Requested-With:*"
    -d "code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
        client_id=your_client_id&
        redirect_uri=https://myapp.com/redirect&
        grant_type=authorization_code&
        code_verifier=the_code_verifier_of_step_1"
The following snippet shows a sample response:
{
  "access_token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI5MiIsImlzcyI6ImNsaWVudDoxMjM0NTY3ODkwIiwiZXhwIjoxNDk1MTkyNDc3LCJzY29wZSI6IndyaXRlX2RlcGFydG1lbnQsY2lhb19kZXBhcnRtZW50LHJlYWRfZGVwYXJ0bWVudCJ9.12SP1CxlOriw0BN7d7IfodSDMKa1umEGoX9IHiHzw3klfBvsFom2WnI3cEtBKDrAMfSAvJ0zgTbGzDuK3JzGMw",
   "expires_in":3600,
  "token_type":"Bearer",
  "refresh_token":"35bf9322-ccf5-4d42-9dfd-67584d76f46b"
}

After the web server receives the authorization code, it can exchange the authorization code for an access token.

To exchange an authorization code for an access token, call the https://api.cassanova.com/oauth/token endpoint and set the following parameters:

Parameter Description
code The authorization code returned from the initial request.
client_id The client ID obtained from the API Console.
redirect_uri One of the redirect URIs listed for your project in the API Console.
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code.
code_verifier The code verifier you created in Step 1.

CassaNova responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

The response contains the following fields:

Parameter Description
access_token The token that your application sends to authorize a CassaNova API request.
refresh_token A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access.
expires_in The remaining lifetime of the access token in seconds.
token_type The type of token returned. At this time, this field’s value is always set to Bearer.

Refreshing an access token

The following snippet shows a sample request:

curl -X POST "https://api.cassanova.com/oauth/token"
    -H "Content-Type:application/x-www-form-urlencoded"
    -H "X-Requested-With:*"
    -d "client_id=your_client_id&
        client_secret=your_client_secret&
        grant_type=refresh_token&
        refresh_token=the_refresh_token"
The following snippet shows a sample response:
{
  "access_token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI5MiIsImlzcyI6ImNsaWVudDoxMjM0NTY3ODkwIiwiZXhwIjoxNDk1MTkyNDc3LCJzY29wZSI6IndyaXRlX2RlcGFydG1lbnQsY2lhb19kZXBhcnRtZW50LHJlYWRfZGVwYXJ0bWVudCJ9.12SP1CxlOriw0BN7d7IfodSDMKa1umEGoX9IHiHzw3klfBvsFom2WnI3cEtBKDrAMfSAvJ0zgTbGzDuK3JzGMw",
  "expires_in":3600,
  "token_type":"Bearer"
}

Access tokens periodically expire. You can refresh an access token without prompting the user for permission (including when the user is not present).

To refresh the access token, call the https://api.cassanova.com/oauth/token endpoint and set the following parameters:

Parameter Description
refresh_token The refresh token returned from the authorization code exchange.
client_id The client ID obtained from the API Console.
client_secret The client secret obtained from the API Console.
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of refresh_token.

The response contains the following fields:

Parameter Description
access_token The token that your application sends to authorize a CassaNova API request.
expires_in The remaining lifetime of the access token in seconds.
token_type The type of token returned. At this time, this field’s value is always set to Bearer.

Revoking a token

curl "https://api.cassanova.com/oauth/revoke?token={refresh_token}"
     -H "Content-Type:application/x-www-form-urlencoded"

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Settings. It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes or removes an application. In other words, part of the removal process can include an API request to ensure the permissions granted to the application are removed.

Using Api-Key to Access CassaNova APIs

CassaNova APIs use also the api-key for authentication and authorization.

To begin, obtain an api-key authentication from the MyCassaNova Console. Then your client application requests an access token from the CassaNova Authorization Server, extracts a token from the response, and sends the token to the CassaNova API that you want to access.

Basic steps

All applications follow a basic pattern when accessing a CassaNova API using Api-Key. At a high level, you follow three steps:

1. Obtain Api-Key credentials from the MyCassaNova Console.

Visit the MyCassaNova Console to obtain an Api-Key credentials known to both CassaNova and your application. A single api-key can grant varying degrees of access to multiple APIs. A variable parameter called scope controls the set of resources and operations that an access token permits.

2. Obtain an access token from the CassaNova Authorization Server.

Before your application can access private data using a CassaNova API, it must obtain an access token that grants access to that API.

To obtain an access token you must make a request to the authorization server sending the api-key.

The following snippet shows a sample request:

curl -X POST "https://api.cassanova.com/apikey/token"
    -H "Content-Type:application/json"
    -H "X-Requested-With:*"
    -d "{"apiKey":<api-key>}"
The following snippet shows a sample response:
{
  "access_token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI5MiIsImlzcyI6ImNsaWVudDoxMjM0NTY3ODkwIiwiZXhwIjoxNDk1MTkyNDc3LCJzY29wZSI6IndyaXRlX2RlcGFydG1lbnQsY2lhb19kZXBhcnRtZW50LHJlYWRfZGVwYXJ0bWVudCJ9.12SP1CxlOriw0BN7d7IfodSDMKa1umEGoX9IHiHzw3klfBvsFom2WnI3cEtBKDrAMfSAvJ0zgTbGzDuK3JzGMw",
  "expires_in":3600,
  "token_type":"Bearer"
}

3. Send the access token to an API.

After an application obtains an access token, it sends the token to a CassaNova API in an HTTP authorization header.

Access tokens are valid only for the set of operations and resources described in the scope of the token request.

Parameters

In the documentation there are several examples of service calls. To test them use “https://api.cassanova.com” as “hostname”.

Timestamp fields follow the format “yyyy-mm-dd”.

Common parameters

Parameter Type Description
id String Id of the entity. It is an UUID (Universally Unique IDentifier) string used to identify an entity with near certainty that the identifier does not duplicate one that has already been, or will be, created to identify something else. This ID is always internally created by APIs and can never be modified.
idSalesPoint Long Id of the sales point related to the entity. This field also defines wether this entity is visible at sales point or account level. If is set, the entity is at sales point level, otherwise if is not set it is at account level. Entities at account level are visible from all account’s sales points, whereas entities at sales point level are visible only from sales point identified by this ID. After entity creation, this field cannot be changed.
internalId String String code for free usages (without constraints). Field used by CassaNova clients from some search functionality.
externalId String String code with unique constraint used by import/export feature. Entities imported from third part systems are identified by this code.
lastUpdate Timestamp Timestamp of the entity last update.

Common filter parameters

Parameter Type Description
start Integer An index from which records are returned. For instance if you make a request with start value 100, the first 99 records will not be returned.
limit Integer A limit on the number of records to be returned, between 1 and 100 with default value 10.
idsSalesPoint List[Long] A list of idSalesPoint, to which the returned records must be related to.
lastUpdateFrom Timestamp Only records updated at or after this time are returned.
lastUpdateTo Timestamp Only records updated at or before this time are returned.

Colors

The “color” parameter refers generally to buttons background on CassaNova selling interface.

For instance it is possible to select different colors for every product kind, in order to increase user experience when selecting sell items.

The following table contains all the available color values.

Value Color
d177ab
 
7e4e60
 
ae7ff9
 
bfa4d6
 
61c0b6
 
3e767a
 
98c32c
 
49b76c
 
70a8eb
 
0a7cad
 
94d4ef
 
ebbd1d
 
ffd993
 
a88a5c
 
e8864a
 
db4925
 
cccccc
 
7f7f7f
 
333333
 

Icons

It is possible to assign the following icons to products. They are shown on product buttons on CassaNova selling interface.

Icon id Description Icon Icon id Description Icon
accendino Lighter lattina Can
acqua Water macedonia Fruit salad
bancomat ATM matita Pencil
batteria Battery minestra Soup
bevanda_analcolica Soft drink occhiali Glasses
bevanda_calda Hot beverage panino Hamburger
burrocacao Chapstick pasta Pasta
busta Envelope penna Pen
caffe Coffee pizza Pizza
caramella Candy postepay Credit carc
cartolina Postcard primo First course
cerotto Patch quaderno Notebook
contorno Side dish secondo_carne_bianca White meat course
dolce Dessert secondo_carne_rossa Red meat course
fiammifero Match secondo_pesce Fish course
fotocopia Photocopy shortino Shot
francobollo Stamp sigaretta Cigarette
frappe Milkshake spremuta Juice
gelato Ice cream stampa Print
ghiacciolo Popsicle superalcolico Alcoholic
gioco Toy tea Tea
giornale Newspaper tramezzino Sandwich
gratta_e_vinci Lottery scratch vino_bicchiere Wine glass
insalata Salad vino_bottiglia Wine bottle

Tax Management

NewTax

Since version: 1.0.0

curl -X POST "<hostname>/taxes
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        rate: BigDecimal,
        externalId: String,
        idSalesPoint: Long
    }

Create a new Tax.

HTTP Request

GET "<hostname>/taxes"

Query Parameters

Parameter Type Description
description String Required. Description.
rate BigDecimal Required. Ratio, expressed as percentage, at which tax is applied.
externalId String externalId.
idSalesPoint Long idSalesPoint.

Response

Parameter Type Description
id String Id of the created tax.

EditTax

Since version: 1.0.0

curl -X PUT "<hostname>/taxes/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        externalId: String
    }

Update the Tax of the specified id.

HTTP Request

GET "<hostname>/taxes/:id"

Query Parameters

Parameter Type Description
description String Description.
externalId String externalId.

DeleteTax

Since version: 1.0.0

curl -X DELETE "<hostname>/taxes/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Tax of the specified id.

HTTP Request

GET "<hostname>/taxes/:id"

GetTax

Since version: 1.0.0

curl -X GET "<hostname>/taxes/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Tax of the specified id.

HTTP Request

GET "<hostname>/taxes/:id"

Response

Parameter Type Description
tax Tax Returned record.

GetTaxes

Since version: 1.0.0

curl -X GET "<hostname>/taxes?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&description=<String>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the taxes within search parameters.

HTTP Request

GET "<hostname>/taxes"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of taxes to retrieve.
idsSalesPoint List[Long] idsSalesPoint.
description String Text, case not sensitive, which returned records description is like to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
taxes List[Tax] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Department Management

NewDepartment

Since version: 1.0.0

curl -X POST "<hostname>/departments
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        descriptionLabel: String,
        descriptionReceipt: String,
        idTax: String,
        color: String,
        amountLimit: BigDecimal,
        externalId: String,
        idSalesPoint: Long
    }

Create a new Department.

HTTP Request

GET "<hostname>/departments"

Query Parameters

Parameter Type Description
description String Required. Description.
descriptionLabel String Required. Label of department button on selling interface.
descriptionReceipt String Required. Description shown on receipt. It’s recommended to not use special characters as some printers may not recognize them.
idTax String Required. Id of the Tax to be applied on the department.
color String Required. Background color, expressed as hexadecimal, of department button on selling interface. See colors for a list of the available values.
amountLimit BigDecimal Optional value used to set amount limit on a department sale (without specifying product). This could help to prevent user errors when inputing prices manually.
externalId String externalId.
idSalesPoint Long idSalesPoint.

Response

Parameter Type Description
id String Id of the created department.

EditDepartment

Since version: 1.0.0

curl -X PUT "<hostname>/departments/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        descriptionLabel: String,
        descriptionReceipt: String,
        idTax: String,
        color: String,
        amountLimit: BigDecimal,
        externalId: String
    }

Update the Department of the specified id.

HTTP Request

GET "<hostname>/departments/:id"

Query Parameters

Parameter Type Description
description String Description.
descriptionLabel String Label of department button on selling interface.
descriptionReceipt String Description shown on receipt. It’s recommended to not use special characters as some printers may not recognize them.
idTax String Id of the Tax to be applied on the department.
color String Background color, expressed as hexadecimal, of department button on selling interface. See colors for a list of the available values.
amountLimit BigDecimal Optional value used to set amount limit on a department sale (without specifying product). This could help to prevent user errors when inputing prices manually.
externalId String externalId.

DeleteDepartment

Since version: 1.0.0

curl -X DELETE "<hostname>/departments/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Department of the specified id.

HTTP Request

GET "<hostname>/departments/:id"

GetDepartment

Since version: 1.0.0

curl -X GET "<hostname>/departments/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Department of the specified id.

HTTP Request

GET "<hostname>/departments/:id"

Response

Parameter Type Description
department Department Returned record.

GetDepartments

Since version: 1.0.0

curl -X GET "<hostname>/departments?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&description=<String>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the departments.

HTTP Request

GET "<hostname>/departments"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of departments to retrieve.
idsSalesPoint List[Long] idsSalesPoint.
description String Text, case not sensitive, which returned records description is like to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
departments List[Department] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Option Management

NewOption

Since version: 1.0.0

curl -X POST "<hostname>/options
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        externalId: String,
        idSalesPoint: Long,
        values: [
                 {
                          type: OptionValueType,
                          value: String,
                          position: Integer,
                          externalId: String
                 }
        ]
    }

Create a new Option.

HTTP Request

GET "<hostname>/options"

Query Parameters

Parameter Type Description
description String Required. Description.
externalId String externalId.
idSalesPoint Long idSalesPoint.
values [
   {
      type: OptionValueType,
      value: String,
      position: Integer,
      externalId: String
   }
]
Required. Array containing option values. For each value ‘type’, ‘value’, ‘position’ are required fields. See OptionValue for further details.

Response

Parameter Type Description
id String Id of the option created.

EditOption

Since version: 1.0.0

curl -X PUT "<hostname>/options/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        externalId: String,
        values: [
                 {
                          type: OptionValueType,
                          value: String,
                          position: Integer,
                          externalId: String
                 }
        ]
    }

Update the Option of the specified id.

HTTP Request

GET "<hostname>/options/:id"

Query Parameters

Parameter Type Description
description String Description.
externalId String externalId.
values [
   {
      type: OptionValueType,
      value: String,
      position: Integer,
      externalId: String
   }
]
Array replacing option values. For each value ‘type’, ‘value’, ‘position’ are required fields. See OptionValue for further details.

DeleteOption

Since version: 1.0.0

curl -X DELETE "<hostname>/options/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Option of the specified id.

HTTP Request

GET "<hostname>/options/:id"

GetOption

Since version: 1.0.0

curl -X GET "<hostname>/options/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Option of the specified id.

HTTP Request

GET "<hostname>/options/:id"

Response

Parameter Type Description
option Option Returned record.

GetOptions

Since version: 1.0.0

curl -X GET "<hostname>/options?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&description=<String>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the options.

HTTP Request

GET "<hostname>/options"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of options to retrieve.
idsSalesPoint List[Long] idsSalesPoint.
description String Text, case not sensitive, which returned records description is like to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
options List[Option] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Category Management

NewCategory

Since version: 1.0.0

curl -X POST "<hostname>/categories
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        externalId: String,
        idSalesPoint: Long,
        enableForRisto: Boolean,
        enableForSale: Boolean,
        enableForECommerce: Boolean,
        enableForMobileCommerce: Boolean,
        enableForSelfOrderMenu: Boolean,
        enableForKiosk: Boolean,
        modifiers: [
                 {
                          idOption: String,
                          position: Integer,
                          values: [
                                   {
                                            idValue: String,
                                            price: BigDecimal,
                                            percentagePrice: BigDecimal
                                   }
                          ]
                 }
        ]
    }

Create a new Category.

HTTP Request

GET "<hostname>/categories"

Query Parameters

Parameter Type Description
description String Required. Description.
externalId String externalId.
idSalesPoint Long idSalesPoint.
enableForRisto Boolean Required. If set to true, all category products are available for the restaurant interface.
enableForSale Boolean Required. If set to true, all category products are available for sale on CassaNova app.
enableForECommerce Boolean Required. If set to true, all category products are available for sale on e-commerce.
enableForMobileCommerce Boolean Required. If set to true, all category products are available for sale on mobile e-commerce.
enableForSelfOrderMenu Boolean Required. If set to true, all category products are available for sale on CassaNova self order app.
enableForKiosk Boolean Required. If set to true, all category products are available for sale on CassaNova kiosk app.
modifiers [
   {
      idOption: String,
      position: Integer,
      values: [
         {
            idValue: String,
            price: BigDecimal,
            percentagePrice: BigDecimal
         }
      ]
   }
]
A collection of modifiers available to all category products. For each modifier ‘idOption’, ‘position’ and ‘values’ are required fields. For each modifier value ‘idValue’ field is required, and one among ‘price’ and ‘percentagePrice’ must be set. See Modifier for further details.

Response

Parameter Type Description
id String Id of the category created.

EditCategory

Since version: 1.0.0

curl -X PUT "<hostname>/categories/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        externalId: String,
        enableForRisto: Boolean,
        enableForSale: Boolean,
        enableForECommerce: Boolean,
        enableForMobileCommerce: Boolean,
        enableForSelfOrderMenu: Boolean,
        enableForKiosk: Boolean,
        modifiers: [
                 {
                          idOption: String,
                          position: Integer,
                          values: [
                                   {
                                            idValue: String,
                                            price: BigDecimal,
                                            percentagePrice: BigDecimal
                                   }
                          ]
                 }
        ]
    }

Update the Category of the specified id.

HTTP Request

GET "<hostname>/categories/:id"

Query Parameters

Parameter Type Description
description String Description.
externalId String externalId.
enableForRisto Boolean If set to true, all category products are available for the restaurant interface.
enableForSale Boolean If set to true, all category products are available for sale on CassaNova app.
enableForECommerce Boolean If set to true, all category products are available for sale on e-commerce.
enableForMobileCommerce Boolean If set to true, all category products are available for sale on mobile e-commerce.
enableForSelfOrderMenu Boolean If set to true, all category products are available for sale on CassaNova self order app.
enableForKiosk Boolean If set to true, all category products are available for sale on CassaNova kiosk app.
modifiers [
   {
      idOption: String,
      position: Integer,
      values: [
         {
            idValue: String,
            price: BigDecimal,
            percentagePrice: BigDecimal
         }
      ]
   }
]
Replaces available modifiers. For each modifier ‘idOption’, ‘position’ and ‘values’ are required fields. For each modifier value ‘idValue’ field is required, and one among ‘price’ and ‘percentagePrice’ must be set. See Modifier for further details.

DeleteCategory

Since version: 1.0.0

curl -X DELETE "<hostname>/categories/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Category of the specified id.

HTTP Request

GET "<hostname>/categories/:id"

GetCategory

Since version: 1.0.0

curl -X GET "<hostname>/categories/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Category of the specified id.

HTTP Request

GET "<hostname>/categories/:id"

Response

Parameter Type Description
category Category Returned record.

GetCategories

Since version: 1.0.0

curl -X GET "<hostname>/categories?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&description=<String>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the categories

HTTP Request

GET "<hostname>/categories"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of categories to retrieve.
idsSalesPoint List[Long] idsSalesPoint.
description String Text, case not sensitive, which returned records description is like to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
categories List[Category] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Organization Management

NewOrganization

Since version: 1.0.0

curl -X POST "<hostname>/organizations
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        name: String,
        address: String,
        city: String,
        zipcode: String,
        district: String,
        country: String,
        vatNumber: String,
        fiscalCode: String,
        phoneNumber: String,
        email: String,
        note: String,
        idSalesPoint: Long
    }

Create a new Organization

HTTP Request

GET "<hostname>/organizations"

Query Parameters

Parameter Type Description
name String Required. Name.
address String Required. Address.
city String Required. City.
zipcode String Required. Zip code.
district String Required. District.
country String Country.
vatNumber String Vat number.
fiscalCode String Fiscal code.
phoneNumber String Phone number.
email String Email.
note String Note.
idSalesPoint Long idSalesPoint.

Response

Parameter Type Description
id String Id of the created organization.

EditOrganization

Since version: 1.0.0

curl -X PUT "<hostname>/organizations/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        name: String,
        address: String,
        city: String,
        zipcode: String,
        district: String,
        country: String,
        vatNumber: String,
        fiscalCode: String,
        phoneNumber: String,
        email: String,
        note: String
    }

Update the Organization of the specified id.

HTTP Request

GET "<hostname>/organizations/:id"

Query Parameters

Parameter Type Description
name String Name.
address String Address.
city String City.
zipcode String Zip code.
district String District.
country String Country.
vatNumber String Vat number.
fiscalCode String Fiscal code.
phoneNumber String Phone number.
email String Email.
note String Note.

DeleteOrganization

Since version: 1.0.0

curl -X DELETE "<hostname>/organizations/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Organization of the specified id.

HTTP Request

GET "<hostname>/organizations/:id"

GetOrganization

Since version: 1.0.0

curl -X GET "<hostname>/organizations/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Organization of the specified id.

HTTP Request

GET "<hostname>/organizations/:id"

Response

Parameter Type Description
organization Organization Returned record.

GetOrganizations

Since version: 1.0.0

curl -X GET "<hostname>/organizations?start=<Integer>&limit=<Integer>&ids=<List[String]>&vatNumber=<String>&fiscalCode=<String>&name=<String>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the organizations.

HTTP Request

GET "<hostname>/organizations"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of organizations to retrieve.
vatNumber String Text, case not sensitive, which returned records vat number is like to.
fiscalCode String Text, case not sensitive, which returned records fiscal code is like to.
name String Text, case not sensitive, which returned records name is like to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
organizations List[Organization] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Customer Management

NewCustomer

Since version: 1.0.0

curl -X POST "<hostname>/customers
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        idOrganization: String,
        name: String,
        dateOfBirth: Datetime,
        gender: CustomerGender,
        address: String,
        city: String,
        zipcode: String,
        district: String,
        country: String,
        vatNumber: String,
        fiscalCode: String,
        phoneNumber: String,
        email: String,
        note: String,
        externalId: String,
        idSalesPoint: Long
    }

Create a new Customer.

HTTP Request

GET "<hostname>/customers"

Query Parameters

Parameter Type Description
idOrganization String Optional value. Id of the organization to which the customer belongs.
name String Required. Name.
dateOfBirth Datetime Required. Date of birth.
gender CustomerGender Required. Gender.
address String Required. Address.
city String Required. City.
zipcode String Required. Zip code.
district String Required. District.
country String Country.
vatNumber String Vat number.
fiscalCode String Fiscal code.
phoneNumber String Phone number.
email String Email.
note String Note.
externalId String externalId.
idSalesPoint Long idSalesPoint.

Response

Parameter Type Description
id String Id of the created customer.

EditCustomer

Since version: 1.0.0

curl -X PUT "<hostname>/customers/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        idOrganization: String,
        name: String,
        dateOfBirth: Datetime,
        gender: CustomerGender,
        address: String,
        city: String,
        zipcode: String,
        district: String,
        country: String,
        vatNumber: String,
        fiscalCode: String,
        phoneNumber: String,
        email: String,
        note: String,
        externalId: String
    }

Update the Customer of the specified id.

HTTP Request

GET "<hostname>/customers/:id"

Query Parameters

Parameter Type Description
idOrganization String Id of the organization to which the customer belongs.
name String
dateOfBirth Datetime
gender CustomerGender
address String
city String
zipcode String
district String
country String
vatNumber String
fiscalCode String
phoneNumber String
email String
note String
externalId String

DeleteCustomer

Since version: 1.0.0

curl -X DELETE "<hostname>/customers/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Customer of the specified id.

HTTP Request

GET "<hostname>/customers/:id"

GetCustomer

Since version: 1.0.0

curl -X GET "<hostname>/customers/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Customer of the specified id.

HTTP Request

GET "<hostname>/customers/:id"

Response

Parameter Type Description
customer Customer Returned record.

GetCustomers

Since version: 1.0.0

curl -X GET "<hostname>/customers?start=<Integer>&limit=<Integer>&ids=<List[String]>&vatNumber=<String>&fiscalCode=<String>&name=<String>&idsOrganization=<List[String]>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the customers

HTTP Request

GET "<hostname>/customers"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of customers to retrieve.
vatNumber String Text, case not sensitive, which returned records vat number is like to.
fiscalCode String Text, case not sensitive, which returned records fiscal code is like to.
name String Text, case not sensitive, which returned records name is like to.
idsOrganization List[String] List containing ids of organization which customers belongs to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
customers List[Customer] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Product Management

NewProduct

Since version: 1.0.0

curl -X POST "<hostname>/products
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        descriptionLabel: String,
        descriptionExtended: String,
        idDepartment: String,
        idCategory: String,
        icon: String,
        soldByWeight: Boolean,
        defaultTare: Long,
        multivariant: Boolean,
        color: String,
        enableForRisto: Boolean,
        enableForSale: Boolean,
        enableForECommerce: Boolean,
        enableForMobileCommerce: Boolean,
        enableForSelfOrderMenu: Boolean,
        enableForKiosk: Boolean,
        tags: List[String],
        externalId: String,
        idSalesPoint: Long,
        descriptionReceipt: String,
        internalId: String,
        barcodes: [
                 {
                          value: String,
                          format: BarcodeFormat,
                          salable: Boolean
                 }
        ],
        prices: [
                 {
                          idSalesMode: String,
                          idSalesPoint: Long,
                          value: BigDecimal
                 }
        ],
        attributes: [
                 {
                          idOption: String,
                          position: Integer,
                          values: [
                                   {
                                            idValue: String
                                   }
                          ]
                 }
        ],
        modifiers: [
                 {
                          idOption: String,
                          position: Integer,
                          values: [
                                   {
                                            idValue: String,
                                            price: BigDecimal,
                                            percentagePrice: BigDecimal
                                   }
                          ]
                 }
        ]
    }

Create a new Product.

HTTP Request

GET "<hostname>/products"

Query Parameters

Parameter Type Description
description String Required.
descriptionLabel String Required. Label of product button on selling interface.
descriptionExtended String Required. Extended description shown on product detail.
idDepartment String Required. Id of the related department.
idCategory String Required. Id of the related category.
icon String Icon id. See icons for a list of available values.
soldByWeight Boolean Required. If set to true, the price is determined by the amount (weight) of product sold.
defaultTare Long If set, this value specify the product default tare weight.
multivariant Boolean Required. If set to true, the product allows variants. See ProductVariant for more details.
color String Product color, expressed as hexadecimal value, show on button background on selling interface.
enableForRisto Boolean Required. If set to true, this product is available for the restaurant interface.
enableForSale Boolean Required. If set to true, this product is available for sale on CassaNova app.
enableForECommerce Boolean Required. If set to true, this product is available for sale on e-commerce.
enableForMobileCommerce Boolean Required. If set to true, this product is available for sale on mobile e-commerce.
enableForSelfOrderMenu Boolean Required. If set to true, this product is available for sale on CassaNova self order app.
enableForKiosk Boolean Required. If set to true, this product is available for sale on CassaNova kiosk app.
tags List[String] Used to group and to help searching products.
externalId String externalId.
idSalesPoint Long idSalesPoint.
descriptionReceipt String Required only if ‘multivariant’ is set to false. Description shown on receipt. If ‘multivariant’ is set to true, the receipt description is taken from product variant. It’s recommended to not use special characters as some printers may not recognize them.
internalId String Required only if ‘multivariant’ is set to false. If ‘multivariant’ is set to true, the internal id is taken from product variant.
barcodes [
   {
      value: String,
      format: BarcodeFormat,
      salable: Boolean
   }
]
List of all product barcodes. For each element all the fields are required. If ‘salable’ is true the barcode is recognized and can be scanned on the selling interface.
prices [
   {
      idSalesMode: String,
      idSalesPoint: Long,
      value: BigDecimal
   }
]
Required. List of all product prices. For each price the field ‘value’ is required. The list must contain at least a price with no sales mode. See SalesMode for further details.
attributes [
   {
      idOption: String,
      position: Integer,
      values: [
         {
            idValue: String
         }
      ]
   }
]
Required only if ‘multivariant’ is set to true. List of all available product attributes. For each attribute all the fields are required. The attribute values must be a subset of the option values. See Attribute for further details.
modifiers [
   {
      idOption: String,
      position: Integer,
      values: [
         {
            idValue: String,
            price: BigDecimal,
            percentagePrice: BigDecimal
         }
      ]
   }
]
List of all available product modifiers. For each modifier all the fields are required. See Modifier for further details.

Response

Parameter Type Description
id String Id of the product created.

EditProduct

Since version: 1.0.0

curl -X PUT "<hostname>/products/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        descriptionLabel: String,
        descriptionExtended: String,
        idDepartment: String,
        idCategory: String,
        icon: String,
        soldByWeight: Boolean,
        defaultTare: Long,
        multivariant: Boolean,
        color: String,
        enableForRisto: Boolean,
        enableForSale: Boolean,
        enableForECommerce: Boolean,
        enableForMobileCommerce: Boolean,
        enableForSelfOrderMenu: Boolean,
        enableForKiosk: Boolean,
        tags: List[String],
        externalId: String,
        descriptionReceipt: String,
        internalId: String,
        barcodes: [
                 {
                          value: String,
                          format: BarcodeFormat,
                          salable: Boolean
                 }
        ],
        prices: [
                 {
                          idSalesMode: String,
                          idSalesPoint: Long,
                          value: BigDecimal
                 }
        ],
        attributes: [
                 {
                          idOption: String,
                          position: Integer,
                          values: [
                                   {
                                            idValue: String
                                   }
                          ]
                 }
        ],
        modifiers: [
                 {
                          idOption: String,
                          position: Integer,
                          values: [
                                   {
                                            idValue: String,
                                            price: BigDecimal,
                                            percentagePrice: BigDecimal
                                   }
                          ]
                 }
        ]
    }

Update the Product of the specified id.

HTTP Request

GET "<hostname>/products/:id"

Query Parameters

Parameter Type Description
description String Description.
descriptionLabel String Label of product button on selling interface.
descriptionExtended String Extended description shown on product detail.
idDepartment String Id of the related department.
idCategory String Id of the related category.
icon String Icon id. See icons for a list of available values.
soldByWeight Boolean If set to true, the price is determined by the amount (weight) of product sold.
defaultTare Long If set, this value specify the product default tare weight.
multivariant Boolean If set to true, the product allows variants. See ProductVariant for more details.
color String Product color, expressed as hexadecimal value, show on button background on selling interface.
enableForRisto Boolean If set to true, this product is available for the restaurant interface.
enableForSale Boolean If set to true, this product is available for sale on CassaNova app.
enableForECommerce Boolean If set to true, this product is available for sale on e-commerce.
enableForMobileCommerce Boolean If set to true, this product is available for sale on mobile e-commerce.
enableForSelfOrderMenu Boolean If set to true, this product is available for sale on CassaNova self order app.
enableForKiosk Boolean If set to true, this product is available for sale on CassaNova kiosk app.
tags List[String] Used to group and to help searching products.
externalId String externalId.
descriptionReceipt String Description shown on receipt. If ‘multivariant’ is set to true, the receipt description is taken from product variant. It’s recommended to not use special characters as some printers may not recognize them.
internalId String If ‘multivariant’ is set to true, the internal id is taken from product variant.
barcodes [
   {
      value: String,
      format: BarcodeFormat,
      salable: Boolean
   }
]
List of all product barcodes. For each element all the fields are required. If ‘salable’ is true the barcode is recognized and can be scanned on the selling interface.
prices [
   {
      idSalesMode: String,
      idSalesPoint: Long,
      value: BigDecimal
   }
]
List of all product prices. For each price the field ‘value’ is required. The list must contain at least a price with no sales mode. See SalesMode for further details.
attributes [
   {
      idOption: String,
      position: Integer,
      values: [
         {
            idValue: String
         }
      ]
   }
]
List of all available product attributes. For each attribute all the fields are required. The attribute values must be a subset of the option values. See Attribute for further details.
modifiers [
   {
      idOption: String,
      position: Integer,
      values: [
         {
            idValue: String,
            price: BigDecimal,
            percentagePrice: BigDecimal
         }
      ]
   }
]
List of all available product modifiers. For each modifier all the fields are required. See Modifier for further details.

DeleteProduct

Since version: 1.0.0

curl -X DELETE "<hostname>/products/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Product of the specified id.

HTTP Request

GET "<hostname>/products/:id"

GetProduct

Since version: 1.0.0

curl -X GET "<hostname>/products/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Product of the specified id.

HTTP Request

GET "<hostname>/products/:id"

Response

Parameter Type Description
product Product Returned record.

GetProducts

Since version: 1.0.0

curl -X GET "<hostname>/products?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&idsCategory=<List[String]>&idsDepartment=<List[String]>&description=<String>&barcodes=<List[String]>&multiVariant=<Boolean>&tags=<List[String]>&menu=<Boolean>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the products.

HTTP Request

GET "<hostname>/products"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of products to retrieve.
idsSalesPoint List[Long] idsSalesPoint.
idsCategory List[String] Used to retrieve all the products belonging to specified categories.
idsDepartment List[String] Used to retrieve all the products belonging to specified departments.
description String Text, case not sensitive, which returned records description is like to.
barcodes List[String] Used to retrieve all the products having specified barcodes.
multiVariant Boolean Used to filter product with or without variants.
tags List[String] Used to filter products by tag.
menu Boolean
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
products List[Product] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

ProductVariant Management

NewProductVariant

Since version: 1.0.0

curl -X POST "<hostname>/products/:idproduct/variants
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        descriptionReceipt: String,
        internalId: String,
        barcodes: [
                 {
                          value: String,
                          format: BarcodeFormat,
                          salable: Boolean
                 }
        ],
        attributes: [
                 {
                          idOption: String,
                          idOptionValue: String
                 }
        ],
        prices: [
                 {
                          idSalesMode: String,
                          idSalesPoint: Long,
                          value: BigDecimal
                 }
        ]
    }

Create a new ProductVariant.

HTTP Request

GET "<hostname>/products/:idproduct/variants"

Query Parameters

Parameter Type Description
description String Description of the product variant. Default is the description of the product.
descriptionReceipt String Required. Description shown on receipt. It’s recommended to not use special characters as some printers may not recognize them.
internalId String Internal id.
barcodes [
   {
      value: String,
      format: BarcodeFormat,
      salable: Boolean
   }
]
List of product barcodes. For each barcode all fields are required. If ‘salable’ is set to true the barcode can be scanned and recognized on selling interface.
attributes [
   {
      idOption: String,
      idOptionValue: String
   }
]
List of attribute values defining the variant. Option and values must be among the product available attributes and values. For each different attribute at most one value can be selected.
prices [
   {
      idSalesMode: String,
      idSalesPoint: Long,
      value: BigDecimal
   }
]
List of all product variant prices depending on sales mode.

Response

Parameter Type Description
id String Id of the product variant created.

EditProductVariant

Since version: 1.0.0

curl -X PUT "<hostname>/products/:idproduct/variants/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        descriptionReceipt: String,
        internalId: String,
        barcodes: [
                 {
                          value: String,
                          format: BarcodeFormat,
                          salable: Boolean
                 }
        ],
        attributes: [
                 {
                          idOption: String,
                          idOptionValue: String
                 }
        ],
        prices: [
                 {
                          idSalesMode: String,
                          idSalesPoint: Long,
                          value: BigDecimal
                 }
        ]
    }

Update the ProductVariant of the specified id.

HTTP Request

GET "<hostname>/products/:idproduct/variants/:id"

Query Parameters

Parameter Type Description
description String Description of the product variant. Default is the description of the product.
descriptionReceipt String Description shown on receipt. It’s recommended to not use special characters as some printers may not recognize them.
internalId String Internal id.
barcodes [
   {
      value: String,
      format: BarcodeFormat,
      salable: Boolean
   }
]
List of product barcodes. For each barcode all fields are required. If ‘salable’ is set to true the barcode can be scanned and recognized on selling interface.
attributes [
   {
      idOption: String,
      idOptionValue: String
   }
]
List of attribute values defining the variant. Option and values must be among the product available attributes and values. For each different attribute at most one value can be selected.
prices [
   {
      idSalesMode: String,
      idSalesPoint: Long,
      value: BigDecimal
   }
]
List of all product variant prices depending on sales mode.

DeleteProductVariant

Since version: 1.0.0

curl -X DELETE "<hostname>/products/:idproduct/variants/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the ProductVariant of the specified id.

HTTP Request

GET "<hostname>/products/:idproduct/variants/:id"

GetProductVariant

Since version: 1.0.0

curl -X GET "<hostname>/products/:idproduct/variants/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the ProductVariant of the specified id.

HTTP Request

GET "<hostname>/products/:idproduct/variants/:id"

Response

Parameter Type Description
variant ProductVariant Returned record.

GetProductVariants

Since version: 1.0.0

curl -X GET "<hostname>/products/:idproduct/variants?start=<Integer>&limit=<Integer>&ids=<List[String]>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the product variants.

HTTP Request

GET "<hostname>/products/:idproduct/variants"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. start.
ids List[String] List containing ids of product variants to retrieve.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
variants List[ProductVariant] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

SalesMode Management

NewSalesMode

Since version: 1.0.0

curl -X POST "<hostname>/salesmodes
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String,
        idSalesPoint: Long
    }

Create a new Salesmode.

HTTP Request

GET "<hostname>/salesmodes"

Query Parameters

Parameter Type Description
description String Required. Description.
idSalesPoint Long idSalesPoint.

Response

Parameter Type Description
id String Id of the created sales mode.

EditSalesMode

Since version: 1.0.0

curl -X PUT "<hostname>/salesmodes/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        description: String
    }

Update the Salesmode of the specified id.

HTTP Request

GET "<hostname>/salesmodes/:id"

Query Parameters

Parameter Type Description
description String Description.

DeleteSalesMode

Since version: 1.0.0

curl -X DELETE "<hostname>/salesmodes/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Salesmode of the specified id.

HTTP Request

GET "<hostname>/salesmodes/:id"

GetSalesMode

Since version: 1.0.0

curl -X GET "<hostname>/salesmodes/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Salesmode of the specified id.

HTTP Request

GET "<hostname>/salesmodes/:id"

Response

Parameter Type Description
salesMode SalesMode Returned record.

GetSalesModes

Since version: 1.0.0

curl -X GET "<hostname>/salesmodes?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&description=<String>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all the Salesmode.

HTTP Request

GET "<hostname>/salesmodes"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of sales modes to retrieve.
idsSalesPoint List[Long] idsSalesPoint.
description String Text, case not sensitive, which returned records description is like to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
salesModes List[SalesMode] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Supplier Management

NewSupplier

Since version: 1.0.0

curl -X POST "<hostname>/suppliers
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        name: String,
        vatNumber: String,
        taxCode: String,
        street: String,
        city: String,
        zipcode: String,
        district: String,
        country: String,
        phoneNumber: String,
        email: String,
        note: String,
        externalId: String,
        idSalesPoint: Long
    }

Create a new Supplier.

HTTP Request

GET "<hostname>/suppliers"

Query Parameters

Parameter Type Description
name String Required.
vatNumber String Required.
taxCode String
street String
city String
zipcode String
district String
country String
phoneNumber String
email String
note String
externalId String externalId.
idSalesPoint Long idSalesPoint.

Response

Parameter Type Description
id String Id of the created supplier.

EditSupplier

Since version: 1.0.0

curl -X PUT "<hostname>/suppliers/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        name: String,
        vatNumber: String,
        taxCode: String,
        street: String,
        city: String,
        zipcode: String,
        district: String,
        country: String,
        phoneNumber: String,
        email: String,
        note: String,
        externalId: String
    }

Update the Supplier of the specified id.

HTTP Request

GET "<hostname>/suppliers/:id"

Query Parameters

Parameter Type Description
name String
vatNumber String
taxCode String
street String
city String
zipcode String
district String
country String
phoneNumber String
email String
note String
externalId String externalId.

DeleteSupplier

Since version: 1.0.0

curl -X DELETE "<hostname>/suppliers/:id
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"

Delete the Supplier of the specified id.

HTTP Request

GET "<hostname>/suppliers/:id"

GetSuppliers

Since version: 1.0.0

curl -X GET "<hostname>/suppliers?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&name=<String>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all suppliers.

HTTP Request

GET "<hostname>/suppliers"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
ids List[String] List containing ids of suppliers to retrieve.
idsSalesPoint List[Long] idsSalesPoint.
name String Text, case not sensitive, which returned records name is like to.
lastUpdateFrom Timestamp lastUpdateFrom.
lastUpdateTo Timestamp lastUpdateTo.

Response

Parameter Type Description
suppliers List[Supplier] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

GetSupplier

Since version: 1.0.0

curl -X GET "<hostname>/suppliers/:id?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Supplier of the specified id.

HTTP Request

GET "<hostname>/suppliers/:id"

Response

Parameter Type Description
supplier Supplier Returned record.

SalesPoint Management

GetSalesPoint

Since version: 1.0.0

curl -X GET "<hostname>/salespoint?"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve all sales points.

HTTP Request

GET "<hostname>/salespoint"

Response

Parameter Type Description
salesPoint List[SalesPoint] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

Stock Management

GetStock

Since version: 1.0.0

curl -X GET "<hostname>/stocks/:idSalesPoint?start=<Integer>&limit=<Integer>&idProduct=<List[String]>&idProductVariant=<List[String]>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the Stock of a product or a product variant for the specified sales point

HTTP Request

GET "<hostname>/stocks/:idSalesPoint"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idProduct List[String] List containing ids of products of which retrieve stock entity.
idProductVariant List[String] List containing ids of products variants of which retrieve stock entity.

Response

Parameter Type Description
stocks List[Stock]
totalCount Integer

EditStock

Since version: 1.0.0

curl -X PUT "<hostname>/stocks/:idSalesPoint
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        idProduct: String,
        idProductVariant: String,
        manageStock: Boolean,
        warningLevel: BigDecimal
    }

Update the Stock configuration of a product or product variant for the specified sales point.

HTTP Request

GET "<hostname>/stocks/:idSalesPoint"

Query Parameters

Parameter Type Description
idProduct String Required if product is not multivariant.
idProductVariant String Required if product is multivariant.
manageStock Boolean If set to false it’s not possible to create movements for product and it’s stock quantity will not be traced.
warningLevel BigDecimal Defines the quantity under which the product should be replenished.

StockMovement Management

GetStockMovements

Since version: 1.0.0

curl -X GET "<hostname>/stocks/:idSalesPoint/movements?start=<Integer>&limit=<Integer>&idProduct=<List[String]>&idProductVariant=<List[String]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve the stock movements of a product or a product variant for the specified sales point.

HTTP Request

GET "<hostname>/stocks/:idSalesPoint/movements"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idProduct List[String] List containing ids of products of which retrieve stock movements.
idProductVariant List[String] List containing ids of product variants of which retrieve stock movements.
datetimeFrom Timestamp Only stock movement at or after this time will be considered. The time span must be smaller than a week.
datetimeTo Timestamp Only stock movement at or before this time will be considered. The time span must be smaller than a week.

Response

Parameter Type Description
stockMovements List[StockMovement] Collection of returned records.
totalCount Integer The total number of records matching filter parameters.

NewStockMovement

Since version: 1.0.0

curl -X POST "<hostname>/stocks/:idSalesPoint/movements
    -H "Content-Type:application/json"
    -H "X-Requested-With: *"
    -H "X-Version: 1.0.0"
    -H "Authorization: Bearer <bearer-token>"
    -d {
        idProduct: String,
        idProductVariant: String,
        quantity: BigDecimal,
        note: String,
        reason: MovementType
    }

Create a new stock movement for the specified sales point.

HTTP Request

GET "<hostname>/stocks/:idSalesPoint/movements"

Query Parameters

Parameter Type Description
idProduct String Required if product is not multivariant.
idProductVariant String Required if product is multivariant.
quantity BigDecimal Amount moved. The quantity cannot decrease more of the current stock level.
note String
reason MovementType

Response

Parameter Type Description
id String Id of the created stock movement.

SoldByTax Management

GetSoldByTax

Since version: 1.0.0

curl -X GET "<hostname>/reports/sold/taxes?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve sold by tax report

HTTP Request

GET "<hostname>/reports/sold/taxes"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than a year.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than a year.

Response

Parameter Type Description
totalCount Integer Total number of different taxes applied in the selected time span.
totalSold BigDecimal Total income in the selected time span.
totalRefund BigDecimal Total refund in the selected time span.
totalQuantity BigDecimal Total amount of items sold in the selected time span.
sold List[SoldByTax] Returned records.

SoldByCategory Management

GetSoldByCategory

Since version: 1.0.0

curl -X GET "<hostname>/reports/sold/categories?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve sold by category report

HTTP Request

GET "<hostname>/reports/sold/categories"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than a year.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than a year.

Response

Parameter Type Description
totalCount Integer Total number of different categories sold in the selected time span.
totalSold BigDecimal Total income from category sales in the selected time span.
totalRefund BigDecimal Total refund of category sales in the selected time span.
totalQuantity BigDecimal Total amount of items sold in the selected time span.
totalDepartmentSold BigDecimal Total income from departments sales (with no product) in the selected time span.
totalDepartmentRefund BigDecimal Total refund of departments sales (with no product) in the selected time span.
totalDepartmentQuantity BigDecimal Total amount of departments sales (with no product) in the selected time span.
sold List[SoldByCategory] Returned records.

SoldByDepartment Management

GetSoldByDepartment

Since version: 1.0.0

curl -X GET "<hostname>/reports/sold/departments?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve sold by department report

HTTP Request

GET "<hostname>/reports/sold/departments"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than a year.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than a year.

Response

Parameter Type Description
totalCount Integer Total number of different departments applied in the selected time span.
totalSold BigDecimal Total income in the selected time span.
totalRefund BigDecimal Total refund in the selected time span.
totalQuantity BigDecimal Total amount of items sold in the selected time span.
sold List[SoldByDepartment] Returned records.

SoldByProduct Management

GetSoldByProduct

Since version: 1.0.0

curl -X GET "<hostname>/reports/sold/products?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&idProducts=<List[String]>&idDepartments=<List[String]>&idCategories=<List[String]>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve sold by product report

HTTP Request

GET "<hostname>/reports/sold/products"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than a year.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than a year.
idProducts List[String] List containing product it to consider.
idDepartments List[String] List of departments ids to which considered products must be related.
idCategories List[String] List of categories ids which considered products belong to.

Response

Parameter Type Description
totalCount Integer Total number of different products sold in the selected time span.
totalSold BigDecimal Total income from products sales in the selected time span.
totalRefund BigDecimal Total refund of products sales in the selected time span.
totalQuantity BigDecimal Total amount of items sold in the selected time span.
totalDepartmentSold BigDecimal Total income from departments sales (with no product) in the selected time span.
totalDepartmentRefund BigDecimal Total refund of departments sales (with no product) in the selected time span.
totalDepartmentQuantity BigDecimal Total amount of departments sales (with no product) in the selected time span.
sold List[SoldByProduct] Returned records.

Documents Management

GetReceipts

Since version: 1.0.0

curl -X GET "<hostname>/documents/receipts?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve receipts

HTTP Request

GET "<hostname>/documents/receipts"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than 3 days.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than 3 days.
numbers List[Long] Used to retrieve all the receipts with specified numbers.
idOrganizations List[String] Used to retrieve all the receipts belonging to specified organizations.
idCustomers List[String] Used to retrieve all the receipts belonging to specified customers.

Response

Parameter Type Description
totalCount Integer Total number of receipts.
receipts List[Receipt] Returned records.

GetInvoices

Since version: 1.0.0

curl -X GET "<hostname>/documents/invoices?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&status=<DocumentStatus>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve invoices

HTTP Request

GET "<hostname>/documents/invoices"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than 3 days.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than 3 days.
status DocumentStatus Used to filter credit notes by their status.
numbers List[Long] Used to retrieve all the invoices with specified numbers.
idOrganizations List[String] Used to retrieve all the invoices belonging to specified organizations.
idCustomers List[String] Used to retrieve all the invoices belonging to specified customers.

Response

Parameter Type Description
totalCount Integer Total number of invoices.
invoices List[Invoice] Returned records.

GetCreditNotes

Since version: 1.0.0

curl -X GET "<hostname>/documents/creditnotes?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&status=<DocumentStatus>&refundNumbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve credit notes

HTTP Request

GET "<hostname>/documents/creditnotes"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than 3 days.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than 3 days.
status DocumentStatus Used to filter credit notes by their status.
refundNumbers List[Long] Used to retrieve all the credit notes with specified refund numbers.
idOrganizations List[String] Used to retrieve all the credit notes belonging to specified organizations.
idCustomers List[String] Used to retrieve all the credit notes belonging to specified customers.

Response

Parameter Type Description
totalCount Integer Total number of credit notes.
creditnotes List[CreditNote] Returned records.

GetBills

Since version: 1.0.0

curl -X GET "<hostname>/documents/bills?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&idOrganizations=<List[String]>&idCustomers=<List[String]>"
    -H "Content-Type:application/json"
    -H "X-Version: 1.0.0" 
    -H "Authorization: Bearer <bearer-token>"

Retrieve bills

HTTP Request

GET "<hostname>/documents/bills"

Query Parameters

Parameter Type Description
start Integer Required. start.
limit Integer Required. limit.
idsSalesPoint List[Long] idsSalesPoint.
datetimeFrom Timestamp Required. Only sales done at or after this time will be considered. The time span must be smaller than 3 days.
datetimeTo Timestamp Only sales done at or before this time will be considered. The time span must be smaller than 3 days.
idOrganizations List[String] Used to retrieve all the bills belonging to specified organizations.
idCustomers List[String] Used to retrieve all the bills belonging to specified customers.

Response

Parameter Type Description
totalCount Integer Total number of bills.
bills List[Bill] Returned records.

Entities

Attribute

Attribute is an option used to define a ProductVariant. This better suit the retail scenario where a product can have several variants as ‘Size’ or ‘Color’.

Parameter Type Description
id String Id.
position Integer Display order.
option Option The attribute extends an option.
values List[AttributeValue] Attribute possible values. This collection is a subset of the related option values. For instance two different products can have attributes based on the same option but with different values sets.

AttributeValue

Parameter Type Description
id String Id.
value OptionValue Attribute value is based on an option value.

Barcode

Parameter Type Description
value String Barcode.
format BarcodeFormat Barcode format.
salable Boolean If set to true, the barcode can be scanned and recognized on selling interface.

Bill

Parameter Type Description
id String Id.
document Document Body of the bill.
datetime Datetime Registration date.

Category

Category is a collection of products. It’s meant to globally define some properties and which modifiers are available to all of its products. These are in addition to product defined properties and modifiers, in case of conflict product defined properties and modifier have higher priority.

Parameter Type Description
id String Id.
description String Description.
externalId String externalId.
enableForRisto Boolean If set to true, all category products are available for the restaurant interface.
enableForSale Boolean If set to true, all category products are available for sale on CassaNova app.
enableForECommerce Boolean If set to true, all category products are available for sale on e-commerce.
enableForMobileCommerce Boolean If set to true, all category products are available for sale on mobile e-commerce.
enableForSelfOrderMenu Boolean If set to true, all category products are available for sale on CassaNova self order app.
enableForKiosk Boolean If set to true, all category products are available for sale on CassaNova kiosk app.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.
modifiers List[Modifier] A collection of modifiers available to all category products.

CreditNote

Parameter Type Description
id String Id.
status DocumentStatus
refundNumber Long Number of the credit note.
receiptNumber Long Number of the receipt to which the credit note refers.
date Timestamp Creation date.
datetime Datetime Registration date.
document Document Body of the credit note.
documentNumbering DocumentNumbering Credit note prefix or suffix, can be null.

Customer

Parameter Type Description
id String Id.
idOrganization String Id of related organization.
organization Organization Related organization.
name String Name.
dateOfBirth Datetime Date of birth.
gender CustomerGender Gender.
vatNumber String Vat number.
fiscalCode String Fiscal code.
address String Address.
city String City.
zipcode String Zip code.
district String District.
country String Country.
phoneNumber String Phone number.
email String Email.
note String Note.
externalId String externalId.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

Department

Parameter Type Description
id String Id.
description String Description.
descriptionLabel String String used to display department buttons on selling interface.
descriptionReceipt String Description shown on receipt. It’s recommended to not use special characters as some printers may not recognize them.
idTax String Id of the Tax applied on department.
tax Tax Tax applied on department.
color String Department color, expressed as hexadecimal value, show on button background on sale interface.
amountLimit BigDecimal Optional value used to set amount limit on a department sale (without specifying product). This could help to prevent user errors when inputing prices manually.
externalId String externalId.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

Document

Represent the body of a receipt, invoice, credit note or bill.

Parameter Type Description
id String Id.
idOrganization String Id of the Organization(#organization) to which the document refers. Only one between idOrganization and idCustomer is defined.
idCustomer String Id of the Customer(#customer) to which the document refers. Only one between idOrganization and idCustomer is defined.
taxFree Boolean If set to true, tax free VAT is applied to all the rows of the document.
amount BigDecimal Total amount of the document.
change BigDecimal Change of the document.
rows List[Row] List of rows of the document.
payments List[Payment] List of payments associated to the document.
orderSummary OrderSummary
user User Details of the user who creates the document.
note String Additional note.

DocumentNumbering

Represent a document numbering line, that can be a prefix or suffix. Each document type has it’s own document numbering lines.

Parameter Type Description
id String Id.
prefix String The document numbering is a prefix of the number of the document. Only one between prefix and suffix is defined.
suffix String The document numbering is a suffix of the number of the document. Only one between prefix and suffix is defined.
documentNumberingType DocumentNumberingType Type of the document to which the document numbering refers.

Invoice

Fiscal invoice document.

Parameter Type Description
id String Id.
status DocumentStatus
number Long Number of the document.
date Timestamp Creation date.
datetime Datetime Registration date.
dueDatetime Datetime Expiration date.
deferred Boolean If set to true then the invoice is a deferred invoice. Deferred invoice has no body (document is null) but has the list of the related receipts (deferredReceipts).
paymentType InvoicePaymentType Payment type.
paymentNote String Note associated to the payment.
payed Boolean If set to true, the invoices has been payed.
shipping Boolean If set to true the the invoice is a shipping invoice.
transportReason String If shipping is set to true, reason of the transport.
transporter Transporter If shipping is set to true, transporter.
carrier String If shipping is set to true, name of the carrier.
destination String If shipping is set to true, destination of the delivery.
weight BigDecimal If shipping is set to true, total weight.
packages Integer If shipping is set to true, number of packages in the invoice.
appearance String If shipping is set to true, appearance of the items.
transportNote String If shipping is set to true, additional transport notes.
document Document Body of the invoice.
deferredReceipts List[String] List of id of the receipts related to the invoice.
documentNumbering DocumentNumbering Invoice prefix or suffix, can be null.

Modifier

Modifier is an option that can be applied ‘on the fly’ to a product. Modifiers better suit the restaurant scenario, where products can have additions or removals.

Parameter Type Description
id String Id.
position Integer Display order.
option Option The modifier extends an option.
values List[ModifierValue] Modifier possible values. This collection is a subset of the related option values. For instance two different products can have modifier based on the same option but with different values sets.

ModifierValue

Modifier value extends option value defining its price.

Parameter Type Description
id String Id.
price BigDecimal Incremental price change applied to the product if the current modifier value is selected. Only one between incremental and percentage price should be defined.
percentagePrice BigDecimal Percentage price change applied to the product if the current modifier value is selected. Only one between incremental and percentage price should be defined.
value OptionValue Modifier value is based on an option value.

Option

An option is a custom criteria used to describe a product. For instance ‘Size’ can be an option for a t-shirt and ‘Topping’ can be an option for coffee. An option can be used as Attribute or Modifier

Parameter Type Description
id String Id.
description String Description.
externalId String externalId.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.
values List[OptionValue] List of the all the possible option values.

OptionValue

Defines a value for an option. For instance ‘XS’, ‘S’, ‘M’, ‘L’ can be values of the ‘Size’ option.

Parameter Type Description
id String Id.
type OptionValueType Specifies whether the selected value is an addition or a removal or a neutral change to the original product.
value String Option value.
position Integer Display order.
externalId String externalId.
lastUpdate Timestamp lastUpdate.

OrderSummary

Parameter Type Description
openingTime Datetime Opening time of the table.
closingTime Datetime Closing time of the table.
amount BigDecimal Total amount of the order.
covers Integer Number of covers of the table.
tableName String Table name.

Organization

Parameter Type Description
id String Id.
name String Name.
address String Address.
city String City.
zipcode String Zip code.
district String District.
country String Country.
vatNumber String Vat number.
fiscalCode String Fiscal code.
phoneNumber String Phone number.
email String Email.
note String Note.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

Payment

Parameter Type Description
id String Id.
paymentType PaymentType Payment type.
amount BigDecimal Amount of the payment.

Price

For every product must be defined at least one default price (with no related sales mode).

Parameter Type Description
idSalesMode String Id of related sales mode.
idSalesPoint Long idSalesPoint.
value BigDecimal Price.

Product

Product is the main entity of the system, at the base of whole sales process. It is a salable object, manageable in warehouse, which can be analyzed through some reports (sales, warehouse stock, supplies …).

A product is defined by this properties:

Some properties usage depends on product variability configurations (descriptionReceipt, barcodes, internalId).

In warehouse management the base unit for multivariant products are its product variants.

Parameter Type Description
id String Id.
description String Description.
descriptionLabel String String used to display department buttons on selling interface.
descriptionExtended String Extended description shown on product detail.
idDepartment String Id of the related department.
department Department Related department which define tax fee on product.
idCategory String Id of the category to which product belongs.
category Category Category to which product belongs.
icon String Optional value. Product icon id. See icons for a list of possible values.
soldByWeight Boolean If set to true, the price is determined by the amount (weight) of product sold.
defaultTare Long If set, this value specify the product default tare weight.
multivariant Boolean If set to true, the product allows variants. See ProductVariant for more details.
color String Product color, expressed as hexadecimal value, show on button background on selling interface.
enableForRisto Boolean If set to true, this product is available for the restaurant interface.
enableForSale Boolean If set to true, this product is available for sale on CassaNova app.
enableForECommerce Boolean If set to true, this product is available for sale on e-commerce.
enableForMobileCommerce Boolean If set to true, this product is available for sale on mobile e-commerce.
enableForSelfOrderMenu Boolean If set to true, this product is available for sale on CassaNova self order app.
enableForKiosk Boolean If set to true, this product is available for sale on CassaNova kiosk app.
tags List[String] Used to group and to help searching products.
descriptionReceipt String Description shown on receipt. If ‘multivariant’ is set to true, the receipt description is taken from product variant. It’s recommended to not use special characters as some printers may not recognize them.
internalId String If ‘multivariant’ is set to true, the internal id is taken from product variant.
barcodes List[Barcode] List of barcodes that identify product. If ‘multivariant’ is set to true, the barcodes are taken from product variant.
variants List[ProductVariant] Product variants. Only set if ‘multivariant’ is true.
attributes List[Attribute] List of all available attributes for the product.
modifiers List[Modifier] List of all available modifier for the product.
prices List[Price] List of all product prices depending on sales mode. Contains at least base price (with no sales mode).
externalId String externalId.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

ProductVariant

A product variant is defined by a combination of the product attributes values for products defined as multivariant.

Parameter Type Description
id String Id.
description String Description.
descriptionReceipt String Description shown on receipt. It’s recommended to not use special characters as some printers may not recognize them.
internalId String Internal id.
barcodes List[Barcode] List of product barcodes.
attributes List[SkuAttribute] The attributes values defining the variant. For instance if a product has ‘Size’, ‘Color’ and ‘Material’ as attributes then a possible variant is [ Size M, Color Black, Material Cotton] or [ Size L, Color White].
prices List[Price] List of all product prices depending on sales mode. If no prices are defined, it will inherit parent product prices.

Receipt

Fiscal receipt document.

Parameter Type Description
id String Id.
number Long Number of the document.
date Timestamp Creation date.
datetime Datetime Registration date.
document Document Body of the receipt.

Row

Every document is composed of one or multiple rows. Any row represents a product sale, department sale, cover charge or subtotal. The amount of the row must be calculated taking into account price, quantity, percentage variation, variation, modifiers and subtotal percentage variations.

Parameter Type Description
id String Id.
subtotal Boolean If set to true, the row is a subtotal.
refund Boolean If set to true, the row is a return.
menu Boolean If set to true, the row contains a menu item.
coverCharge Boolean If set to true, the row is a cover charge.
idProduct String Id of the Product. Could be null if the row represents a subtotal, department sales or cover charge.
idProductVariant String Id of the ProductVariant if the product is ‘multivariant’. Could be null if the row represents a subtotal, department sales or cover charge.
idCategory String Id of the Category of the product at the time of sale..
idDepartment String Id of the Department. If idProduct and idProductVariant are both null the row represents a department sale.
idTax String Id of the Tax applied on department at the time of sale.
idSalesMode String Id of the SalesMode at the time of sale.
stockMovementEnabled Boolean If set to true, the row generate a stock movement equal to the row quantity.
idStockMovement String Id of the StockMovement.
rowNumber Integer Row number, useful to order the rows.
quantity BigDecimal Quantity of the row.
price BigDecimal Price of the row.
percentageVariation BigDecimal Percentage variation applied on the row. If < 0 then is surcharge otherwise is a discount.
variation BigDecimal Variation applied on the row. If < 0 then is surcharge otherwise is a discount.
variationType VariationType Type of the variation applied.
rowModifierValues List[RowModifierValue] List of the modifiers applied to the row.
note String Additional note.

RowModifierValue

Parameter Type Description
id String Id.
idModifierValue String Id of the Modifier applied to the row.
price BigDecimal Incremental price change of the modifier at the time of sale. Only one between incremental and percentage price is defined.
percentagePrice BigDecimal Percentage price change of the modifier at the time of sale. Only one between incremental and percentage price is defined.

SalesMode

Sales modes allows too apply different set of prices. If a product does not specify a price for the selected sales mode the default price will be applied.

Parameter Type Description
id String Id.
description String Description.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

SalesPoint

Parameter Type Description
id Long Id.
name String Name.
description String Description.
latitude BigDecimal Latitude.
longitude BigDecimal Longitude.
brand String Brand.
street String Street.
city String City.
zipcode String Zip code.
district String District.
country String Country.
vatNumber String Vat number.
taxCode String Tax code.
phoneNumber String Phone number.
email String Email.

SkuAttribute

A sku attribute is an option value used to define product variants.

Parameter Type Description
idOption String
idOptionValue String
option Option This option refers to an attribute.
value OptionValue This value must be among the attribute available values.

SoldByCategory

Parameter Type Description
idCategory String Category id.
category Category Category.
quantity BigDecimal Amount of category items sold.
profit BigDecimal Profit.
percentTotal BigDecimal Percentage of total amount.

SoldByDepartment

Parameter Type Description
idDepartment String Department id.
department Department Department.
quantity BigDecimal Amount of department sales.
profit BigDecimal Profit.
percentTotal BigDecimal Percentage of total amount.

SoldByProduct

Parameter Type Description
idProduct String Product id.
product Product Product.
quantity BigDecimal Amount of product sold.
profit BigDecimal Profit.
percentTotal BigDecimal Percentage of total amount.

SoldByTax

Parameter Type Description
idTax String Tax id.
tax Tax Tax.
quantity BigDecimal Amount of items sold applying this tax.
profit BigDecimal Profit.
taxable BigDecimal Income.
vat BigDecimal Vat applied.
percentTotal BigDecimal Percentage of total amount.

Stock

Stock entity is related to a product or to a product variant (if product is multivariant), it’s key is composed by ‘idProduct’ and ‘idProductVariant’ fields. It defines product stock properties.

Parameter Type Description
idProduct String Id of the product.
idProductVariant String Id of the variant if the product is ‘multivariant’.
manageStock Boolean If set to false it’s not possible to create movements for product and it’s stock quantity will not be traced.
warningLevel BigDecimal Defines the quantity under which the product should be replenished.
quantity BigDecimal Product stock quantity.

StockMovement

Parameter Type Description
id String Id.
idProduct String Related product (‘multivariant’ set to false).
idProductVariant String Related product variant (‘multivariant’ set to true).
quantity BigDecimal Moved amount.
date Timestamp Movement time stamp.
note String Note.
reason MovementType Movement reason.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

Supplier

Parameter Type Description
id String Id.
name String Name.
vatNumber String Vat number.
taxCode String Tax code.
street String Street.
city String City.
zipcode String Zip code.
district String District.
country String Country.
phoneNumber String Phone number.
email String Email.
note String Note.
externalId String externalId.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

Tax

Parameter Type Description
id String Id.
description String Description.
rate BigDecimal Ratio, expressed as percentage, at which tax is applied.
externalId String externalId.
idSalesPoint Long idSalesPoint.
lastUpdate Timestamp lastUpdate.

User

Parameter Type Description
id String Id.
name String Name of the user.

Enumerations

BarcodeFormat


EAN13
CODE39

CustomerGender


MALE
FEMALE

DocumentNumberingType


INVOICE
CREDITNOTE
ORDER
DDT
QUOTATION
PURCHASE_INVOICE
PURCHASE_ORDER
PURCHASE_DDT

DocumentStatus


DRAFT
CONFRIMED

InvoicePaymentType


CASH
BANK_TRANSFER
RIBA_30
RIBA_60
CHEQUE
CREDIT_CARD
PAYPAL
OTHER

MovementType


SALE
SUPPLY
THEFT
LOSS
CORRECTION
RETURN_FROM_CUSTOMER
RETURN_TO_SUPPLIER
TRANSFER
DEFECTIVE
FREE_SAMPLE
CONSUMABLES
SELF_CONSUMPTION
TASTING
EXPIRED

OptionValueType

Specify whether the selected value is an addition or a removal or a neutral change to the original product. It can be used to group the modifiers applied to a product.


POSITIVE
NEGATIVE
NEUTRAL

PaymentType


CASH
BANKCHECK
CASHCARD
CREDITCARD
TICKET
DEFERRED
FIDELITYCARD
VOUCHER

Transporter


VECTOR
SENDER
RECEIVER

VariationType


CUSTOMER
ORGANIZATION
FIDELITY_CIRCUIT
ROUNDING