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. Contact us to receive your ID.
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. 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 are available only with Retail Enterprise or Risto Enterprise licenses and use the api-key for authentication and authorization.

To begin, contact us to obtain an api-key. 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.

Contact us to obtain your Api-Key credentials. 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.
sorts	Sorts (#sort)	A sort policy. Key is the name of the field. Direction could be 1 (Ascending) or -1 (Descending).

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,
        nature: NaturaIvaEsente,
        noFiscalPrint: Boolean,
        noFiscalPrintOnMixedReceipt: Boolean,
        idSalesPoint: Long
    }'

Create a new Tax.

HTTP Request

POST '<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.
nature	NaturaIvaEsente	Type of exemption, valid only if rate is zero.
noFiscalPrint	Boolean	If true the receipt row will not be printed, valid only if rate is zero.
noFiscalPrintOnMixedReceipt	Boolean	If true the receipt row will not be printed even in mixed receipts, valid only if rate is zero.
idSalesPoint	Long	idSalesPoint.

Response

Parameter	Type	Description
id	String	Id of the created tax.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchTax

Since version: 1.0.0

curl -X POST '<hostname>/taxes/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          description: String,
                          rate: BigDecimal,
                          externalId: String,
                          nature: NaturaIvaEsente,
                          noFiscalPrint: Boolean,
                          noFiscalPrintOnMixedReceipt: Boolean,
                          idSalesPoint: Long
                 }
        ],
        update: [
                 {
                          id: String,
                          description: String,
                          externalId: String,
                          nature: NaturaIvaEsente,
                          noFiscalPrint: Boolean,
                          noFiscalPrintOnMixedReceipt: Boolean
                 }
        ]
    }'

Bulk creation/update of Tax.

HTTP Request

POST '<hostname>/taxes/batch'

Query Parameters

Parameter	Type	Description
create	[    {       description: String,       rate: BigDecimal,       externalId: String,       nature: NaturaIvaEsente,       noFiscalPrint: Boolean,       noFiscalPrintOnMixedReceipt: Boolean,       idSalesPoint: Long    } ]	Required. Array containing taxes to be created
update	[    {       id: String,       description: String,       externalId: String,       nature: NaturaIvaEsente,       noFiscalPrint: Boolean,       noFiscalPrintOnMixedReceipt: Boolean    } ]	Required. Array containing taxes to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated taxes.

Errors

Error Code	Description
InvalidId
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type BatchError.

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,
        nature: NaturaIvaEsente,
        noFiscalPrint: Boolean,
        noFiscalPrintOnMixedReceipt: Boolean
    }'

Update the Tax of the specified id.

HTTP Request

PUT '<hostname>/taxes/:id'

Query Parameters

Parameter	Type	Description
description	String	Description.
externalId	String	externalId.
nature	NaturaIvaEsente	Type of exemption, valid only if rate is zero.
noFiscalPrint	Boolean	If true the receipt row will not be printed, valid only if rate is zero.
noFiscalPrintOnMixedReceipt	Boolean	If true the receipt row will not be printed even in mixed receipts, valid only if rate is zero.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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

DELETE '<hostname>/taxes/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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

POST '<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.

Errors

Error Code	Description
InvalidIdSalesPoint
InvalidIdTax
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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

PUT '<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.

Errors

Error Code	Description
InvalidId
InvalidIdTax
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchDepartment

Since version: 1.0.0

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

Bulk creation/update of Department.

HTTP Request

POST '<hostname>/departments/batch'

Query Parameters

Parameter	Type	Description
create	[    {       description: String,       descriptionLabel: String,       descriptionReceipt: String,       idTax: String,       color: String,       amountLimit: BigDecimal,       externalId: String,       idSalesPoint: Long    } ]	Required. Array containing department to be created
update	[    {       id: String,       description: String,       descriptionLabel: String,       descriptionReceipt: String,       idTax: String,       color: String,       amountLimit: BigDecimal,       externalId: String    } ]	Required. Array containing department to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated departments.

Errors

Error Code	Description
InvalidIdSalesPoint
InvalidId
InvalidIdTax
ConflictValue
InvalidValue

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/departments/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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

POST '<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.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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

PUT '<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.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchOption

Since version: 1.0.0

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

Bulk creation/update of Option.

HTTP Request

POST '<hostname>/options/batch'

Query Parameters

Parameter	Type	Description
create	[    {       description: String,       externalId: String,       idSalesPoint: Long,       values: [          {             type: OptionValueType,             value: String,             position: Integer,             externalId: String          }       ]    } ]	Required. Array containing options to be created
update	[    {       id: String,       description: String,       externalId: String,       values: [          {             type: OptionValueType,             value: String,             position: Integer,             externalId: String          }       ]    } ]	Required. Array containing options to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated options.

Errors

Error Code	Description
InvalidId
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/options/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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
                                   }
                          ]
                 }
        ],
        imageUrl: String
    }'

Create a new Category.

HTTP Request

POST '<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 Cassa In Cloud 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 Cassa In Cloud self order app.
enableForKiosk	Boolean	Required. If set to true, all category products are available for sale on Cassa In Cloud 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.
imageUrl	String	Link to an image connected to the category.

Response

Parameter	Type	Description
id	String	Id of the category created.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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
                                   }
                          ]
                 }
        ],
        imageUrl: String
    }'

Update the Category of the specified id.

HTTP Request

PUT '<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 Cassa In Cloud 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 Cassa In Cloud self order app.
enableForKiosk	Boolean	If set to true, all category products are available for sale on Cassa In Cloud 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.
imageUrl	String	Link to an image connected to the category.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchCategory

Since version: 1.0.0

curl -X POST '<hostname>/categories/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          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
                                                     }
                                            ]
                                   }
                          ],
                          imageUrl: String
                 }
        ],
        update: [
                 {
                          id: String,
                          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
                                                     }
                                            ]
                                   }
                          ],
                          imageUrl: String
                 }
        ]
    }'

Bulk creation/update of Category.

HTTP Request

POST '<hostname>/categories/batch'

Query Parameters

Parameter	Type	Description
create	[    {       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                }             ]          }       ],       imageUrl: String    } ]	Required. Array containing categories to be created
update	[    {       id: String,       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                }             ]          }       ],       imageUrl: String    } ]	Required. Array containing categories to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated categories.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue
InvalidId

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/categories/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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,
        splitPayment: Boolean,
        country: String,
        vatNumber: String,
        fiscalCode: String,
        eInvoiceCode: String,
        pec: String,
        phoneNumber: String,
        email: String,
        note: String,
        idSalesPoint: Long,
        idSalesMode: String,
        bankAccountHolder: String,
        bankAccountInstitute: String,
        bankAccountIBAN: String
    }'

Create a new Organization

HTTP Request

POST '<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.
splitPayment	Boolean	Required. SplitPayment
country	String	Country.
vatNumber	String	Vat number.
fiscalCode	String	Fiscal code.
eInvoiceCode	String	Invoice code.
pec	String	Pec.
phoneNumber	String	Phone number.
email	String	Email.
note	String	Note.
idSalesPoint	Long	idSalesPoint.
idSalesMode	String	Id of related sales mode.
bankAccountHolder	String	Bank account holder.
bankAccountInstitute	String	Bank account institute.
bankAccountIBAN	String	Bank account IBAN.

Response

Parameter	Type	Description
id	String	Id of the created organization.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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,
        splitPayment: Boolean,
        country: String,
        vatNumber: String,
        fiscalCode: String,
        eInvoiceCode: String,
        pec: String,
        phoneNumber: String,
        email: String,
        note: String,
        idSalesMode: String,
        bankAccountHolder: String,
        bankAccountInstitute: String,
        bankAccountIBAN: String
    }'

Update the Organization of the specified id.

HTTP Request

PUT '<hostname>/organizations/:id'

Query Parameters

Parameter	Type	Description
name	String	Name.
address	String	Address.
city	String	City.
zipcode	String	Zip code.
district	String	District.
splitPayment	Boolean	SplitPayment
country	String	Country.
vatNumber	String	Vat number.
fiscalCode	String	Fiscal code.
eInvoiceCode	String	Invoice code.
pec	String	Pec.
phoneNumber	String	Phone number.
email	String	Email.
note	String	Note.
idSalesMode	String	Id of related sales mode.
bankAccountHolder	String	Bank account holder.
bankAccountInstitute	String	Bank account institute.
bankAccountIBAN	String	Bank account IBAN.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchOrganization

Since version: 1.0.0

curl -X POST '<hostname>/organizations/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          name: String,
                          address: String,
                          city: String,
                          zipcode: String,
                          district: String,
                          splitPayment: Boolean,
                          country: String,
                          vatNumber: String,
                          fiscalCode: String,
                          eInvoiceCode: String,
                          pec: String,
                          phoneNumber: String,
                          email: String,
                          note: String,
                          idSalesPoint: Long,
                          idSalesMode: String,
                          bankAccountHolder: String,
                          bankAccountInstitute: String,
                          bankAccountIBAN: String
                 }
        ],
        update: [
                 {
                          id: String,
                          name: String,
                          address: String,
                          city: String,
                          zipcode: String,
                          district: String,
                          splitPayment: Boolean,
                          country: String,
                          vatNumber: String,
                          fiscalCode: String,
                          eInvoiceCode: String,
                          pec: String,
                          phoneNumber: String,
                          email: String,
                          note: String,
                          idSalesMode: String,
                          bankAccountHolder: String,
                          bankAccountInstitute: String,
                          bankAccountIBAN: String
                 }
        ]
    }'

Bulk creation/update of Organization.

HTTP Request

POST '<hostname>/organizations/batch'

Query Parameters

Parameter	Type	Description
create	[    {       name: String,       address: String,       city: String,       zipcode: String,       district: String,       splitPayment: Boolean,       country: String,       vatNumber: String,       fiscalCode: String,       eInvoiceCode: String,       pec: String,       phoneNumber: String,       email: String,       note: String,       idSalesPoint: Long,       idSalesMode: String,       bankAccountHolder: String,       bankAccountInstitute: String,       bankAccountIBAN: String    } ]	Required. Array containing organizations to be created
update	[    {       id: String,       name: String,       address: String,       city: String,       zipcode: String,       district: String,       splitPayment: Boolean,       country: String,       vatNumber: String,       fiscalCode: String,       eInvoiceCode: String,       pec: String,       phoneNumber: String,       email: String,       note: String,       idSalesMode: String,       bankAccountHolder: String,       bankAccountInstitute: String,       bankAccountIBAN: String    } ]	Required. Array containing organizations to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated organizations.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue
InvalidId

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/organizations/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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,
        idSalesMode: String,
        bankAccountHolder: String,
        bankAccountInstitute: String,
        bankAccountIBAN: String
    }'

Create a new Customer.

HTTP Request

POST '<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.
idSalesMode	String	Id of related sales mode.
bankAccountHolder	String	Bank account holder.
bankAccountInstitute	String	Bank account institute.
bankAccountIBAN	String	Bank account IBAN.

Response

Parameter	Type	Description
id	String	Id of the created customer.

Errors

Error Code	Description
InvalidIdSalesPoint
InvalidIdOrganization
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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,
        idSalesMode: String,
        bankAccountHolder: String,
        bankAccountInstitute: String,
        bankAccountIBAN: String
    }'

Update the Customer of the specified id.

HTTP Request

PUT '<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
idSalesMode	String	Id of related sales mode.
bankAccountHolder	String	Bank account holder.
bankAccountInstitute	String	Bank account institute.
bankAccountIBAN	String	Bank account IBAN.

Errors

Error Code	Description
InvalidId
InvalidIdOrganization
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchCustomer

Since version: 1.0.0

curl -X POST '<hostname>/customers/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          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,
                          idSalesMode: String,
                          bankAccountHolder: String,
                          bankAccountInstitute: String,
                          bankAccountIBAN: String
                 }
        ],
        update: [
                 {
                          id: String,
                          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,
                          idSalesMode: String,
                          bankAccountHolder: String,
                          bankAccountInstitute: String,
                          bankAccountIBAN: String
                 }
        ]
    }'

Bulk creation/update of Customer.

HTTP Request

POST '<hostname>/customers/batch'

Query Parameters

Parameter	Type	Description
create	[    {       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,       idSalesMode: String,       bankAccountHolder: String,       bankAccountInstitute: String,       bankAccountIBAN: String    } ]	Required. Array containing customers to be created
update	[    {       id: String,       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,       idSalesMode: String,       bankAccountHolder: String,       bankAccountInstitute: String,       bankAccountIBAN: String    } ]	Required. Array containing customers to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated customers.

Errors

Error Code	Description
InvalidIdSalesPoint
InvalidIdOrganization
ConflictValue
InvalidValue
InvalidId

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/customers/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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],
        costs: [
                 {
                          idSupplier: String,
                          cost: BigDecimal,
                          variation1: BigDecimal,
                          variation2: BigDecimal,
                          variation3: BigDecimal,
                          variation4: BigDecimal,
                          idDepartment: 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
                                   }
                          ]
                 }
        ],
        images: [
                 {
                          imageUrl: String
                 }
        ]
    }'

Create a new Product.

HTTP Request

POST '<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 Cassa In Cloud 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 Cassa In Cloud self order app.
enableForKiosk	Boolean	Required. If set to true, this product is available for sale on Cassa In Cloud kiosk app.
tags	List[String]	Used to group and to help searching products.
costs	[    {       idSupplier: String,       cost: BigDecimal,       variation1: BigDecimal,       variation2: BigDecimal,       variation3: BigDecimal,       variation4: BigDecimal,       idDepartment: String    } ]	List of costs
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.
images	[    {       imageUrl: String    } ]	List of all product images. Every entry is an url.

Response

Parameter	Type	Description
id	String	Id of the product created.

Errors

Error Code	Description
InvalidIdDepartment
InvalidIdCategory
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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],
        costs: [
                 {
                          idSupplier: String,
                          cost: BigDecimal,
                          variation1: BigDecimal,
                          variation2: BigDecimal,
                          variation3: BigDecimal,
                          variation4: BigDecimal,
                          idDepartment: 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
                                   }
                          ]
                 }
        ],
        images: [
                 {
                          imageUrl: String
                 }
        ]
    }'

Update the Product of the specified id.

HTTP Request

PUT '<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 Cassa In Cloud 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 Cassa In Cloud self order app.
enableForKiosk	Boolean	If set to true, this product is available for sale on Cassa In Cloud kiosk app.
tags	List[String]	Used to group and to help searching products.
costs	[    {       idSupplier: String,       cost: BigDecimal,       variation1: BigDecimal,       variation2: BigDecimal,       variation3: BigDecimal,       variation4: BigDecimal,       idDepartment: String    } ]	List of costs
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.
images	[    {       imageUrl: String    } ]	List of all product images. Every entry is an url.

Errors

Error Code	Description
InvalidId
InvalidIdDepartment
InvalidIdCategory
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchProduct

Since version: 1.0.0

curl -X POST '<hostname>/products/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          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,
                          costs: [
                                   {
                                            idSupplier: String,
                                            cost: BigDecimal,
                                            variation1: BigDecimal,
                                            variation2: BigDecimal,
                                            variation3: BigDecimal,
                                            variation4: BigDecimal,
                                            idDepartment: 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
                                                     }
                                            ]
                                   }
                          ],
                          images: [
                                   {
                                            imageUrl: String
                                   }
                          ]
                 }
        ],
        update: [
                 {
                          id: String,
                          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,
                          costs: [
                                   {
                                            idSupplier: String,
                                            cost: BigDecimal,
                                            variation1: BigDecimal,
                                            variation2: BigDecimal,
                                            variation3: BigDecimal,
                                            variation4: BigDecimal,
                                            idDepartment: 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
                                                     }
                                            ]
                                   }
                          ],
                          images: [
                                   {
                                            imageUrl: String
                                   }
                          ]
                 }
        ]
    }'

Bulk creation/update of Product.

HTTP Request

POST '<hostname>/products/batch'

Query Parameters

Parameter	Type	Description
create	[    {       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,       costs: [          {             idSupplier: String,             cost: BigDecimal,             variation1: BigDecimal,             variation2: BigDecimal,             variation3: BigDecimal,             variation4: BigDecimal,             idDepartment: 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                }             ]          }       ],       images: [          {             imageUrl: String          }       ]    } ]	Required. Array containing products to be created
update	[    {       id: String,       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,       costs: [          {             idSupplier: String,             cost: BigDecimal,             variation1: BigDecimal,             variation2: BigDecimal,             variation3: BigDecimal,             variation4: BigDecimal,             idDepartment: 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                }             ]          }       ],       images: [          {             imageUrl: String          }       ]    } ]	Required. Array containing products to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated products.

Errors

Error Code	Description
InvalidIdDepartment
InvalidIdCategory
InvalidIdSalesPoint
ConflictValue
InvalidValue
InvalidId

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/products/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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>&externalId=<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 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
externalId	List[String]	Used to retrieve all the products having specified externalId.
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,
        descriptionOrderTicket: String,
        internalId: String,
        costs: [
                 {
                          idSupplier: String,
                          cost: BigDecimal,
                          variation1: BigDecimal,
                          variation2: BigDecimal,
                          variation3: BigDecimal,
                          variation4: BigDecimal,
                          idDepartment: 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

POST '<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.
descriptionOrderTicket	String	Additional description for product variant
internalId	String	Internal id.
costs	[    {       idSupplier: String,       cost: BigDecimal,       variation1: BigDecimal,       variation2: BigDecimal,       variation3: BigDecimal,       variation4: BigDecimal,       idDepartment: String    } ]	List of costs
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.

Errors

Error Code	Description
ConflictValue
InvalidValue
InvalidIdProduct
InvalidAttribute

Error responses may contain details data of following type SyncError.

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,
        descriptionOrderTicket: String,
        internalId: String,
        costs: [
                 {
                          idSupplier: String,
                          cost: BigDecimal,
                          variation1: BigDecimal,
                          variation2: BigDecimal,
                          variation3: BigDecimal,
                          variation4: BigDecimal,
                          idDepartment: 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

PUT '<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.
descriptionOrderTicket	String	Additional description for product variant
internalId	String	Internal id.
costs	[    {       idSupplier: String,       cost: BigDecimal,       variation1: BigDecimal,       variation2: BigDecimal,       variation3: BigDecimal,       variation4: BigDecimal,       idDepartment: String    } ]	List of costs
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.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue
InvalidAttribute

Error responses may contain details data of following type SyncError.

BatchProductVariant

Since version: 1.0.0

curl -X POST '<hostname>/products/:idproduct/variants/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          description: String,
                          descriptionReceipt: String,
                          descriptionOrderTicket: String,
                          internalId: String,
                          costs: [
                                   {
                                            idSupplier: String,
                                            cost: BigDecimal,
                                            variation1: BigDecimal,
                                            variation2: BigDecimal,
                                            variation3: BigDecimal,
                                            variation4: BigDecimal,
                                            idDepartment: String
                                   }
                          ],
                          barcodes: [
                                   {
                                            value: String,
                                            format: BarcodeFormat,
                                            salable: Boolean
                                   }
                          ],
                          attributes: [
                                   {
                                            idOption: String,
                                            idOptionValue: String
                                   }
                          ],
                          prices: [
                                   {
                                            idSalesMode: String,
                                            idSalesPoint: Long,
                                            value: BigDecimal
                                   }
                          ]
                 }
        ],
        update: [
                 {
                          id: String,
                          description: String,
                          descriptionReceipt: String,
                          descriptionOrderTicket: String,
                          internalId: String,
                          costs: [
                                   {
                                            idSupplier: String,
                                            cost: BigDecimal,
                                            variation1: BigDecimal,
                                            variation2: BigDecimal,
                                            variation3: BigDecimal,
                                            variation4: BigDecimal,
                                            idDepartment: String
                                   }
                          ],
                          barcodes: [
                                   {
                                            value: String,
                                            format: BarcodeFormat,
                                            salable: Boolean
                                   }
                          ],
                          attributes: [
                                   {
                                            idOption: String,
                                            idOptionValue: String
                                   }
                          ],
                          prices: [
                                   {
                                            idSalesMode: String,
                                            idSalesPoint: Long,
                                            value: BigDecimal
                                   }
                          ]
                 }
        ]
    }'

Bulk creation/update of ProductVariant.

HTTP Request

POST '<hostname>/products/:idproduct/variants/batch'

Query Parameters

Parameter	Type	Description
create	[    {       description: String,       descriptionReceipt: String,       descriptionOrderTicket: String,       internalId: String,       costs: [          {             idSupplier: String,             cost: BigDecimal,             variation1: BigDecimal,             variation2: BigDecimal,             variation3: BigDecimal,             variation4: BigDecimal,             idDepartment: String          }       ],       barcodes: [          {             value: String,             format: BarcodeFormat,             salable: Boolean          }       ],       attributes: [          {             idOption: String,             idOptionValue: String          }       ],       prices: [          {             idSalesMode: String,             idSalesPoint: Long,             value: BigDecimal          }       ]    } ]	Required. Array containing variants to be created
update	[    {       id: String,       description: String,       descriptionReceipt: String,       descriptionOrderTicket: String,       internalId: String,       costs: [          {             idSupplier: String,             cost: BigDecimal,             variation1: BigDecimal,             variation2: BigDecimal,             variation3: BigDecimal,             variation4: BigDecimal,             idDepartment: String          }       ],       barcodes: [          {             value: String,             format: BarcodeFormat,             salable: Boolean          }       ],       attributes: [          {             idOption: String,             idOptionValue: String          }       ],       prices: [          {             idSalesMode: String,             idSalesPoint: Long,             value: BigDecimal          }       ]    } ]	Required. Array containing variants to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated product variants.

Errors

Error Code	Description
ConflictValue
InvalidValue
InvalidIdProduct
InvalidAttribute
InvalidId
InvalidIdSalesPoint

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/products/:idproduct/variants/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

GetProductVariants

Since version: 1.0.0

curl -X GET '<hostname>/products/:idproduct/variants?start=<Integer>&limit=<Integer>&ids=<List[String]>&externalId=<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.
externalId	List[String]	Used to retrieve all the products having specified externalId.
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

POST '<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.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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

PUT '<hostname>/salesmodes/:id'

Query Parameters

Parameter	Type	Description
description	String	Description.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchSalesMode

Since version: 1.0.0

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

Bulk creation/update of SalesMode.

HTTP Request

POST '<hostname>/salesmodes/batch'

Query Parameters

Parameter	Type	Description
create	[    {       description: String,       idSalesPoint: Long    } ]	Required. Array containing sales mode to be created
update	[    {       id: String,       description: String    } ]	Required. Array containing sales mode to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated sales mode.

Errors

Error Code	Description
InvalidIdSalesPoint
InvalidId
ConflictValue
InvalidValue

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/salesmodes/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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

POST '<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.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

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

PUT '<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.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchSupplier

Since version: 1.0.0

curl -X POST '<hostname>/suppliers/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          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
                 }
        ],
        update: [
                 {
                          id: String,
                          name: String,
                          vatNumber: String,
                          taxCode: String,
                          street: String,
                          city: String,
                          zipcode: String,
                          district: String,
                          country: String,
                          phoneNumber: String,
                          email: String,
                          note: String,
                          externalId: String
                 }
        ]
    }'

Bulk creation/update of Supplier.

HTTP Request

POST '<hostname>/suppliers/batch'

Query Parameters

Parameter	Type	Description
create	[    {       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    } ]	Required. Array containing suppliers to be created
update	[    {       id: String,       name: String,       vatNumber: String,       taxCode: String,       street: String,       city: String,       zipcode: String,       district: String,       country: String,       phoneNumber: String,       email: String,       note: String,       externalId: String    } ]	Required. Array containing suppliers to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created and updated suppliers.

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue
InvalidId

Error responses may contain details data of following type BatchError.

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

DELETE '<hostname>/suppliers/:id'

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue

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.

Errors

Error Code	Description
InvalidId

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

Errors

Error Code	Description
InvalidId
InvalidIdSalesPoint

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,
        incomingQuantity: BigDecimal,
        outgoingQuantity: BigDecimal,
        manageStock: Boolean,
        warningLevel: BigDecimal
    }'

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

HTTP Request

PUT '<hostname>/stocks/:idSalesPoint'

Query Parameters

Parameter	Type	Description
idProduct	String	Required if product is not multivariant.
idProductVariant	String	Required if product is multivariant.
incomingQuantity	BigDecimal	Incoming quantity.
outgoingQuantity	BigDecimal	Outgoing quantity.
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.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue
InvalidIdSalesPoint

Error responses may contain details data of following type SyncError.

BatchStock

Since version: 1.0.0

curl -X POST '<hostname>/stocks/:idSalesPoint/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        update: [
                 {
                          idProduct: String,
                          idProductVariant: String,
                          incomingQuantity: BigDecimal,
                          outgoingQuantity: BigDecimal,
                          manageStock: Boolean,
                          warningLevel: BigDecimal
                 }
        ]
    }'

Bulk update of Stock.

HTTP Request

POST '<hostname>/stocks/:idSalesPoint/batch'

Query Parameters

Parameter	Type	Description
update	[    {       idProduct: String,       idProductVariant: String,       incomingQuantity: BigDecimal,       outgoingQuantity: BigDecimal,       manageStock: Boolean,       warningLevel: BigDecimal    } ]	Required. Array containing stocks to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the updated stocks.

Errors

Error Code	Description
InvalidId
ConflictValue
InvalidValue
InvalidIdSalesPoint

Error responses may contain details data of following type BatchError.

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>&reason=<List[[MovementType](#movementtype)]>'
    -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. At least one field among idProduct, idProductVariant and datetimeFrom must be specified

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.
reason	List[MovementType]	List containing the movement reason to filter.

Response

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

Errors

Error Code	Description
InvalidId
InvalidIdSalesPoint
InvalidValue
InvalidParams

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,
        date: Timestamp
    }'

Create a new stock movement for the specified sales point.

HTTP Request

POST '<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
date	Timestamp	Date of the movement. When the movement was made.

Response

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

Errors

Error Code	Description
InvalidIdSalesPoint
ConflictValue
InvalidValue

Error responses may contain details data of following type SyncError.

BatchStockMovement

Since version: 1.0.0

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

Bulk update of StockMovement.

HTTP Request

POST '<hostname>/stocks/:idSalesPoint/movements/batch'

Query Parameters

Parameter	Type	Description
create	[    {       idProduct: String,       idProductVariant: String,       quantity: BigDecimal,       note: String,       reason: MovementType,       date: Timestamp    } ]	Required. Array containing stock movements to be updated

Response

Parameter	Type	Description
batchResponse	BatchResponse	Id and ExternalId of the created stock movements.

Errors

Error Code	Description
InvalidIdSalesPoint
InvalidValue
ConflictValue

Error responses may contain details data of following type BatchError.

Reconciliation Management

GetReconciliation

Since version: 1.0.0

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

Retrieve the Reconciliation of the specified id.

HTTP Request

GET '<hostname>/reconciliations/:id'

Response

Parameter	Type	Description
reconciliation	Reconciliation	Returned record.

Errors

Error Code	Description
InvalidId

GetReconciliations

Since version: 1.0.0

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

Retrieve reconciliation

HTTP Request

GET '<hostname>/reconciliations'

Query Parameters

Parameter	Type	Description
start	Integer	Required. start.
limit	Integer	Required. limit.
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.
idsSalesPoint	List[Long]	idsSalesPoint.

Response

Parameter	Type	Description
totalCount	Integer	Total number of reconciliation.
reconciliations	List[Reconciliation]	Returned records.

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.

Errors

Error Code	Description
InvalidParams

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.

Errors

Error Code	Description
InvalidParams

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.

Errors

Error Code	Description
InvalidParams

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.

Errors

Error Code	Description
InvalidParams

Documents Management

GetReceipts

Since version: 1.0.0

curl -X GET '<hostname>/documents/receipts?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>&calculatedAmount=<Boolean>'
    -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.
ids	List[String]	Receipts ids.
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.
sorts	List[Sort]	List of sort policy.
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

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

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

GetInvoices

Since version: 1.0.0

curl -X GET '<hostname>/documents/invoices?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>&status=<DocumentStatus>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>&calculatedAmount=<Boolean>'
    -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.
ids	List[String]	Invoices ids.
idsSalesPoint	List[Long]	idsSalesPoint.
datetimeFrom	Timestamp	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.
lastUpdateFrom	Timestamp	Only sales updated at or after this time will be considered. The time span must be smaller than 3 days.
lastUpdateTo	Timestamp	Only sales updated 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.
sorts	List[Sort]	sort.
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

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

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

GetEInvoicesPresignedURL

Since version: 1.0.0

curl -X GET '<hostname>/documents/einvoices/url?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&lastUpdateFrom=<Timestamp>&lastUpdateTo=<Timestamp>&status=<DocumentStatus>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>'
    -H 'Content-Type:application/json'
    -H 'X-Version: 1.0.0' 
    -H 'Authorization: Bearer <bearer-token>'

Retrieve E-Invoices XML presigned URL

HTTP Request

GET '<hostname>/documents/einvoices/url'

Query Parameters

Parameter	Type	Description
start	Integer	Required. start.
limit	Integer	Required. limit.
ids	List[String]	Invoices ids.
idsSalesPoint	List[Long]	idsSalesPoint.
datetimeFrom	Timestamp	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.
lastUpdateFrom	Timestamp	Only sales updated at or after this time will be considered. The time span must be smaller than 3 days.
lastUpdateTo	Timestamp	Only sales updated 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.
sorts	List[Sort]	sort.

Response

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

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

GetDDTs

Since version: 1.0.0

curl -X GET '<hostname>/documents/ddts?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&status=<DocumentStatus>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>&calculatedAmount=<Boolean>'
    -H 'Content-Type:application/json'
    -H 'X-Version: 1.0.0' 
    -H 'Authorization: Bearer <bearer-token>'

Retrieve DDTs

HTTP Request

GET '<hostname>/documents/ddts'

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.
sorts	List[Sort]	sort.
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

Parameter	Type	Description
totalCount	Integer	Total number of ddts.
ddts	List[DDT]	Returned records.

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

GetOrder

Since version: 1.0.0

curl -X GET '<hostname>/documents/orders/:id?calculatedAmount=<Boolean>'
    -H 'Content-Type:application/json'
    -H 'X-Version: 1.0.0' 
    -H 'Authorization: Bearer <bearer-token>'

Retrieve the Order of the specified id.

HTTP Request

GET '<hostname>/documents/orders/:id'

Query Parameters

Parameter	Type	Description
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

Parameter	Type	Description
order	Order	Returned record.

Errors

Error Code	Description
InvalidId

GetOrders

Since version: 1.0.0

curl -X GET '<hostname>/documents/orders?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&status=<DocumentStatus>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>&calculatedAmount=<Boolean>'
    -H 'Content-Type:application/json'
    -H 'X-Version: 1.0.0' 
    -H 'Authorization: Bearer <bearer-token>'

Retrieve orders

HTTP Request

GET '<hostname>/documents/orders'

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.
sorts	List[Sort]	sort.
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

Parameter	Type	Description
totalCount	Integer	Total number of orders.
orders	List[Order]	Returned records.

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

BatchOrder

Since version: 1.0.0

curl -X POST '<hostname>/documents/orders/batch'
    -H 'Content-Type:application/json'
    -H 'X-Requested-With: *'
    -H 'X-Version: 1.0.0'
    -H 'Authorization: Bearer <bearer-token>'
    -d '{
        create: [
                 {
                          externalId: String,
                          internalWorkflowStatus: OrderInternalWorkflowStatus,
                          isExternalOrder: Boolean,
                          status: OrderStatus,
                          date: Timestamp,
                          dueDate: Timestamp,
                          deliveryMode: DeliveryMode,
                          destinationStreet: String,
                          destinationCountry: String,
                          destinationCity: String,
                          destinationZipcode: String,
                          destinationDistrict: String,
                          transportNote: String,
                          phoneNumber: String,
                          prepay: Boolean,
                          prepaymentStatus: PrepaymentStatus,
                          prepaymentTransactionId: String,
                          document: {
                                   idSalesPoint: Long
                                   idOrganization: String
                                   idCustomer: String
                                   taxFree: Boolean
                                   amount: BigDecimal
                                   note: String
                                   rows: [
                                            {
                                                     rowNumber: Integer,
                                                     idProductVariant: String,
                                                     idDepartment: String,
                                                     idTax: String,
                                                     idSalesMode: String,
                                                     quantity: BigDecimal,
                                                     price: BigDecimal,
                                                     subtotal: Boolean,
                                                     shippingCost: Boolean,
                                                     percentageVariation: BigDecimal,
                                                     variation: BigDecimal,
                                                     variationType: VariationType,
                                                     note: String,
                                                     rowModifierValues: [
                                                              {
                                                                       idModifierValue: String,
                                                                       price: BigDecimal,
                                                                       percentagePrice: BigDecimal
                                                              }
                                                     ]
                                            }
                                   ]
                          }
                 }
        ]
    }'

Bulk creation of Order.

HTTP Request

POST '<hostname>/documents/orders/batch'

Query Parameters

Parameter	Type	Description
create	[    {       externalId: String,       internalWorkflowStatus: OrderInternalWorkflowStatus,       isExternalOrder: Boolean,       status: OrderStatus,       date: Timestamp,       dueDate: Timestamp,       deliveryMode: DeliveryMode,       destinationStreet: String,       destinationCountry: String,       destinationCity: String,       destinationZipcode: String,       destinationDistrict: String,       transportNote: String,       phoneNumber: String,       prepay: Boolean,       prepaymentStatus: PrepaymentStatus,       prepaymentTransactionId: String,       document: {          idSalesPoint: Long          idOrganization: String          idCustomer: String          taxFree: Boolean          amount: BigDecimal          note: String          rows: [             {                rowNumber: Integer,                idProductVariant: String,                idDepartment: String,                idTax: String,                idSalesMode: String,                quantity: BigDecimal,                price: BigDecimal,                subtotal: Boolean,                shippingCost: Boolean,                percentageVariation: BigDecimal,                variation: BigDecimal,                variationType: VariationType,                note: String,                rowModifierValues: [                   {                      idModifierValue: String,                      price: BigDecimal,                      percentagePrice: BigDecimal                   }                ]             }          ]       }    } ]	Required. Array containing orders to be created (max 100)

Response

Parameter	Type	Description
batchResponse	BatchCreateResponse	Id and ExternalId of the created orders.

Errors

Error Code	Description
ConflictValue
InvalidValue
InvalidIdSalesPoint
InvalidId
InputSizeExceeded

Error responses may contain details data of following type BatchCreateError.

GetQuotations

Since version: 1.0.0

curl -X GET '<hostname>/documents/quotations?start=<Integer>&limit=<Integer>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&numbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>&calculatedAmount=<Boolean>'
    -H 'Content-Type:application/json'
    -H 'X-Version: 1.0.0' 
    -H 'Authorization: Bearer <bearer-token>'

Retrieve quotations

HTTP Request

GET '<hostname>/documents/quotations'

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 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.
sorts	List[Sort]	sort.
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

Parameter	Type	Description
totalCount	Integer	Total number of quotations.
quotations	List[Quotation]	Returned records.

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

GetCreditNotes

Since version: 1.0.0

curl -X GET '<hostname>/documents/creditnotes?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&status=<DocumentStatus>&refundNumbers=<List[Long]>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>&calculatedAmount=<Boolean>'
    -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.
ids	List[String]	Credit notes ids.
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.
sorts	List[Sort]	sort.
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

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

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

GetBills

Since version: 1.0.0

curl -X GET '<hostname>/documents/bills?start=<Integer>&limit=<Integer>&ids=<List[String]>&idsSalesPoint=<List[Long]>&datetimeFrom=<Timestamp>&datetimeTo=<Timestamp>&idOrganizations=<List[String]>&idCustomers=<List[String]>&sorts=<List[[Sort](#sort)]>&calculatedAmount=<Boolean>'
    -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.
ids	List[String]	Bills ids.
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.
sorts	List[Sort]	sort.
calculatedAmount	Boolean	If set to true, each row as a calculated amount that includes discounts, variations and subtotals.

Response

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

Errors

Error Code	Description
InvalidParams

Error responses may contain details data of following type SortError.

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.

BatchCreateError

Parameter	Type	Description
createErrorDetails	List[BatchErrorDetails]

BatchCreateResponse

Parameter	Type	Description
createDetails	List[EntityDetails]

BatchError

Parameter	Type	Description
createErrorDetails	List[BatchErrorDetails]
updateErrorDetails	List[BatchErrorDetails]

BatchErrorDetails

Parameter	Type	Description
index	Integer
id	String
externalId	String
msg	String
syncErrorType	String
conflictType	String

BatchResponse

Parameter	Type	Description
createDetails	List[EntityDetails]
updateDetails	List[EntityDetails]

BatchUpdateError

Parameter	Type	Description
updateErrorDetails	List[BatchErrorDetails]

BatchUpdateResponse

Parameter	Type	Description
updateDetails	List[EntityDetails]

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 Cassa In Cloud 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 Cassa In Cloud self order app.
enableForKiosk	Boolean	If set to true, all category products are available for sale on Cassa In Cloud kiosk app.
idSalesPoint	Long	idSalesPoint.
lastUpdate	Timestamp	lastUpdate.
modifiers	List[Modifier]	A collection of modifiers available to all category products.
imageUrl	String	Link to an image connected to the category.

Cost

Each product or variant could have a cost

Parameter	Type	Description
id	String	Id.
idSupplier	String	Id of related supplier.
cost	BigDecimal	Cost
variation1	BigDecimal	First variation.
variation2	BigDecimal	Second variation.
variation3	BigDecimal	Third variation.
variation4	BigDecimal	Forth variation.
idDepartment	String	Id related department.

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.
referenceDocumentNumber	String	Reference document number.
referenceDocumentDate	Timestamp	Reference document date.
receiptZNumber	Long	Receipt Z Number.
splitPayment	Boolean	Split payment enabled.
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.
extraDataNature	ExtraDataNature
extraDataCCC	String
extraDataCUP	String
extraDataCIG	String

CustomPayment

Parameter	Type	Description
id	String	Id.
description	String	Description.
collectable	Boolean	If set to true, the custom payment is collectable.
changeEnabled	Boolean	If set to true, the custom payment is enabled to generate change.

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.
idSalesMode	String	Id of related sales mode.
bankAccountHolder	String	Bank account holder.
bankAccountInstitute	String	Bank account institute.
bankAccountIBAN	String	Bank account IBAN.
externalId	String	externalId.
idSalesPoint	Long	idSalesPoint.
lastUpdate	Timestamp	lastUpdate.

DDT

DDT document.

Parameter	Type	Description
id	String	Id.
status	DocumentStatus
number	Long	Number of the document.
date	Timestamp	Creation date.
datetime	Datetime	Registration date.
transportReason	String	If shipping is set to true, reason of the transport.
transporter	Transporter	If shipping is set to true, transporter.
destinationStreet	String	If shipping is set to true, destination street of the delivery.
destinationCountry	String	If shipping is set to true, destination country of the delivery.
destinationCity	String	If shipping is set to true, destination city of the delivery.
destinationZipcode	String	If shipping is set to true, destination zipcode of the delivery.
destinationDistrict	String	If shipping is set to true, destination district of the delivery.
carrierName	String	If shipping is set to true, name of the carrier (legal person).
carrierFirstname	String	If shipping is set to true, first name of the carrier (natural person).
carrierLastname	String	If shipping is set to true, last name of the carrier (natural person).
carrierVatNumber	String	If shipping is set to true, vat number of the carrier.
carrierCountry	String	If shipping is set to true, country of the carrier.
weight	BigDecimal	If shipping is set to true, total weight.
packages	Integer	If shipping is set to true, number of packages in the ddt.
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 ddt.
documentNumbering	DocumentNumbering	DDT prefix or suffix, can be null.

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.
idSalesPoint	Long	idSalesPoint.
idOrganization	String	Id of the Organization(#organization) to which the document refers. At least one between idOrganization and idCustomer is required.
idCustomer	String	Id of the Customer(#customer) to which the document refers. At least one between idOrganization and idCustomer is required.
taxFree	Boolean	If set to true, tax free VAT is applied to all the rows of the document.
confirmed	Boolean	If set to true, document is confirmed, otherwise is draft.
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
userType	UserType	Type of the user who creates the document.
user	User	Details of the user who creates the document.
note	String	Additional note.
documentReason	DocumentReason	Details of the document reason of the document.

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.

DocumentReason

Parameter	Type	Description
id	String	Id.
description	String	Name of the document reason.

EInvoicePresignedURL

Parameter	Type	Description
invoiceId	String	Invoice Id.
eInvoiceURL	String	EInvoice URL.

EntityDetails

Parameter	Type	Description
index	Integer
id	String
externalId	String

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).
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.
destinationStreet	String	If shipping is set to true, destination street of the delivery.
destinationCountry	String	If shipping is set to true, destination country of the delivery.
destinationCity	String	If shipping is set to true, destination city of the delivery.
destinationZipcode	String	If shipping is set to true, destination zipcode of the delivery.
destinationDistrict	String	If shipping is set to true, destination district of the delivery.
carrierName	String	If shipping is set to true, name of the carrier (legal person).
carrierFirstname	String	If shipping is set to true, first name of the carrier (natural person).
carrierLastname	String	If shipping is set to true, last name of the carrier (natural person).
carrierVatNumber	String	If shipping is set to true, vat number of the carrier.
carrierCountry	String	If shipping is set to true, country of the carrier.
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.
extraDataDocumentId	String
extraDataDate	Datetime
extraDataNature	ExtraDataNature
extraDataCCC	String
extraDataCUP	String
extraDataCIG	String

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.

Order

Order document.

Parameter	Type	Description
id	String	Id.
number	Long	Number
idDocumentNumbering	String	ID Document Numbering
documentNumbering	DocumentNumbering	Document Numbering
internalWorkflowStatus	OrderInternalWorkflowStatus	Internal Workflow Status
externalChannel	ExternalChannel	Channel for external-channel orders
externalWorkflowStatus	ExternalWorkflowStatus	External Workflow Status
status	OrderStatus	Order Status
date	Timestamp	Creation date.
datetime	Datetime	Registration date.
dueDate	Timestamp	Due Date
dueDatetime	Datetime	Due Datetime
deliveryMode	DeliveryMode	Delivery mode for external-channel orders
destinationStreet	String	Delivery street for external-channel orders
destinationCountry	String	Delivery country for external-channel orders
destinationCity	String	Delivery city for external-channel orders
destinationZipcode	String	Delivery zip code for external-channel orders
destinationDistrict	String	Delivery district for external-channel orders
transportNote	String	Transport note for external-channel orders
phoneNumber	String	Phone number for external-channel orders
prepay	Boolean	Prepay for external-channel orders
prepaymentType	PrepaymentType	Prepayment type for external-channel orders
prepaymentStatus	PrepaymentStatus	Prepayment status for external-channel orders
prepaymentTransactionId	String	Prepayment transaction Id for external-channel orders
document	Document	Body of the order.

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.
splitPayment	Boolean	Split payment.
country	String	Country.
vatNumber	String	Vat number.
fiscalCode	String	Fiscal code.
eInvoiceCode	String	Invoice code.
pec	String	Pec.
phoneNumber	String	Phone number.
email	String	Email.
note	String	Note.
idSalesMode	String	Id of related sales mode.
bankAccountHolder	String	Bank account holder.
bankAccountInstitute	String	Bank account institute.
bankAccountIBAN	String	Bank account IBAN.
idSalesPoint	Long	idSalesPoint.
lastUpdate	Timestamp	lastUpdate.

OutgoingMovement

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	Outgoing movement time stamp.
reason	MovementType	Outgoing movement reason.
idSalesPoint	Long	idSalesPoint.
lastUpdate	Timestamp	lastUpdate.

Payment

Parameter	Type	Description
paymentType	PaymentType	Payment type.
amount	BigDecimal	Amount of the payment.
paymentNote	String	Note associated to the payment.
bankAccountHolder	String	Bank account holder info for some payment types.
bankAccountInstitute	String	Bank account institute info for some payment types.
bankAccountIBAN	String	Bank account IBAN info for some payment types.
change	BigDecimal	Change amount of the payment.
customPayment	CustomPayment	Details of custom payment.
ticket	Ticket	Details of ticket.

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:

• general (description, category, department, price, modifiers, …)
• visibility (idSalesPoint)
• functional (salable, ristoEnabled, soldByWeight, …)
• variability (multivariant, attributes, variants, …)

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 Cassa In Cloud 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 Cassa In Cloud self order app.
enableForKiosk	Boolean	If set to true, this product is available for sale on Cassa In Cloud 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.
alternatives	List[String]	List of ID of alternative products.
costs	List[Cost]	List of costs.
relateds	List[String]	List of ID of related products.
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).
images	List[ProductImage]	List of all images related to the product.
externalId	String	externalId.
idSalesPoint	Long	idSalesPoint.
lastUpdate	Timestamp	lastUpdate.

ProductImage

List of images url related to the product.

Parameter	Type	Description
imageUrl	String

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.
descriptionOrderTicket	String	Description over ticket
internalId	String	Internal id.
barcodes	List[Barcode]	List of product barcodes.
costs	List[Cost]	List of costs.
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.

Quotation

Order document.

Parameter	Type	Description
id	String	Id.
title	String	Quotation title.
number	Long	Quotation number
idDocumentNumbering	String	Id document numbering
expirationDate	Timestamp	Due Date
expirationDateTime	Datetime	Due Datetime
documentNumbering	DocumentNumbering	Document Numbering
document	Document	Body of the invoice.

Receipt

Fiscal receipt document.

Parameter	Type	Description
id	String	Id.
number	Long	Number of the document.
date	Timestamp	Creation date.
datetime	Datetime	Registration date.
zNumber	Long	Z Number.
taxCode	String	Tax Code.
vatNumber	String	Vat Number.
document	Document	Body of the receipt.

Reconciliation

Parameter	Type	Description
id	String	Id
idSalesAccount	String	Id Sales Account.
number	Long	Number.
receiptsCount	Integer	Receipts count.
receiptsAmount	BigDecimal	Receipts amount.
notCachedAmount	BigDecimal	Not cached amount.
firstInvoice	String	First invoice.
lastInvoice	String	Last invoice.
invoicesCount	Integer	Invoices count.
invoicesFromReceiptsAmount	BigDecimal	Invoices from receipts amount.
directInvoicesAmount	BigDecimal	Direct invoices amount.
creditNotesCount	Integer	Credit notes count.
creditNotesAmount	BigDecimal	Credit notes amount.
canceledCount	Integer	Canceled count.
canceledAmount	BigDecimal	Canceled amount.
idUserFO	Integer	Id User FO.
referenceDate	Datetime	Reference date.
date	Timestamp	Date.
taxes	List[ReconciliationTax]	Taxes.

ReconciliationTax

Parameter	Type	Description
idTax	String	Tax id.
originalReceiptsAmount	BigDecimal	Amount of original receipts.
originalNotCashedAmount	BigDecimal	Amount of original not cached receipts.
originalInvoicesAmount	BigDecimal	Amount of original invoices.
originalCanceledAmount	BigDecimal	Amount of original canceled.
receiptsAmount	BigDecimal	Amount of receipts.
notCashedAmount	BigDecimal	Amount of not cached.
invoicesAmount	BigDecimal	Amount of invoices.
canceledAmount	BigDecimal	Amount of canceled.
creditNotesAmount	BigDecimal	Credit notes amount.
tax	Tax	Taxes.

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.
idOutgoingMovement	String	Id of the OutgoingMovement.
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.
calculatedAmount	BigDecimal	Calculated amount including discounts, variations and subtotals.
shippingCost	Boolean	If set to true, the row is a shipping cost.

RowModifierValue

Parameter	Type	Description
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.

Sort

Parameter	Type	Description
key	String
direction	Integer

SortError

Parameter	Type	Description
msg	String
allowedSort	List[String]

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.
incomingQuantity	BigDecimal	Incoming quantity
outgoingQuantity	BigDecimal	Outgoing quantity
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.
cost	BigDecimal	Product cost at movement time.
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.

SyncError

Parameter	Type	Description
id	String
msg	String
errorType	String

Tax

Parameter	Type	Description
id	String	Id.
description	String	Description.
rate	BigDecimal	Ratio, expressed as percentage, at which tax is applied.
externalId	String	externalId.
nature	NaturaIvaEsente	Type of exemption, valid only if rate is zero.
noFiscalPrint	Boolean	If true the receipt row will not be printed, valid only if rate is zero.
noFiscalPrintOnMixedReceipt	Boolean	If true the receipt row will not be printed even in mixed receipts, valid only if rate is zero.
idSalesPoint	Long	idSalesPoint.
lastUpdate	Timestamp	lastUpdate.

Ticket

Parameter	Type	Description
id	String	Id.
description	String	Description.
quantity	Integer	Number ticket used to pay.
value	BigDecimal	Amount value of each ticket used to pay.

User

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

Enumerations

BarcodeFormat

EAN13
CODE39

CustomerGender

MALE
FEMALE

DeliveryMode

PICKUP
DELIVERY

DocumentNumberingType

INVOICE
CREDITNOTE
ORDER
DDT
QUOTATION
PURCHASE_INVOICE
PURCHASE_ORDER
PURCHASE_DDT

DocumentStatus

DRAFT
CONFRIMED

ExternalChannel

CN_MOBILE_COMMERCE

ExternalWorkflowStatus

REQUESTED
REJECTED
ACCEPTED
PROCESSING
READY
SHIPPING
SHIPPED
DELIVERING
CANCELED
COMPLETED

ExtraDataNature

DATI_ORDINE_ACQUISTO
DATI_CONTRATTO
DATI_CONVENZIONE
DATI_RICEZIONE
DATI_FATTURE_COLLEGATE

MovementType

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

NaturaIvaEsente

N_1
N_2
N_3
N_4
N_5
N_6
N_7

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

OrderInternalWorkflowStatus

PENDING
REJECTED
ADJUSTED
APPROVED

OrderStatus

NOT_PROCESSED
PARTIALLY_PROCESSED
PROCESSED
UNCONFIRMED

PaymentType

CASH
BANKCHECK
CASHCARD
CREDITCARD
TICKET
DEFERRED
FIDELITYCARD
VOUCHER
BANK_TRANSFER
RIBA_30
RIBA_60
PAYPAL
CUSTOM
OTHER

PrepaymentStatus

WAITING
FAILED
PAYED
REFUNDED

PrepaymentType

TSPAY
CN_CREDIT

Transporter

VECTOR
SENDER
RECEIVER

UserType

USER_APP
USER_FO
USER_ECOMMERCE
USER_API
USER_MOBILE_COMMERCE

VariationType

CUSTOMER
ORGANIZATION
FIDELITY_CIRCUIT
ROUNDING