Licensing

The API services are provided according to different hierarchic licenses:

1. API Basic Allows basic data queries for e-com websites and final transaction recording including the retail customer entity. It does not allow loyalty data queries and recording.
   The data exposed through the Basic module includes: Parts basic data, Part characters, Part characters for e-com, Price lists, Warehouses list, Stock volume, Branches and basic POS customers data without loyalty data.
2. Pro Includes queries for commercial and retail customers. Enables new customer record creation. Includes queries for part sets and customer transactions log queries.
3. CLM Facilitates loyalty interface includes: loyalty registration, customer's assets queries and creation and customer segments queries and creation.
4. Cart Complete cart interface including usage of loyalty assets and payment by gift cards. Enables purchase of new gift card and charging existing card. Includes queries for part campaigns and promotions.
5. CRM Customer's service calls queries and recording. This module supports also in Serial parts queries and new serial part registering.
6. POS used for different kinds of POS such as: mobile POS or web POS
7. Events Events and ticketing queries, including open seats.

The license type which unlocks each query is mentioned next to the query description in brackets.

Priority Products Licensing

General definitions and instructions

The data interchange protocol used by the API is REST. All the services and queries included in the API can accept parameters and return data and error codes in REST protocol.
The REST protocol is used between the API and the external terminal only. All the queries validates the unique terminal identifier and returns an error code in case the terminal is not properly registered.

Queries which returns arrays, will return empty arrays in case no relevant data was retrieved.

Priority API integration guide

Error handling infrastructure

All queries will return an error structure named EdeaError.
One of the characters of the EdeaError structure is the ErrorSource. When this character holds a value other than '0', an error has occurred.
If the value held by the ErrorSource is 5 (Five), the error is a business logic error. In this case the ErrorCode character should be addressed to retrieve the specific error.
Note: that in some cases the value in the ErrorCode might refer to another error object in the error structure, for example:
The ErrorSource object in the EdeaError structure returned the value 5 (Five) which indicates a business logic error when the "Register Final Order" method had been approached.
The ErrorCode field returned the value 6 (six). This value indicates an error in creating or updating a POS customer record. In order to identify the specific error returned from this service, the value returned in the ErrorCode of the "Create or Update POS Customer" error object should be referred to.

The application manages a locking mechanism to prevent executing simultaneous operations on the same transaction. The lock is based on the temporary transaction number.
When an operation is received at the same time on the same transaction, the error code will be -10 - Operation already executing on same entity. In this case the operation should be retried after a short delay.
For example:
If 30 requests to update the a transaction were sent at the same time, and 10 of them were on the same transaction number and other 20 are for different transaction numbers each, only one of the 10 operations will be able to execute and other 9 operations will receive an error code of -10 and will have to try again.
The rest of the 20 operations, since they're each for a separate transaction number will execute in parallel.
Creating a new transaction is limited with this locking mechanism, but is based on point sale and branch code instead of the temporary transaction number.
Since the specific operations execute fast, the definition of simultaneous is at the second or less.

Error codes

Data compressing

The REST API uses gzip for data compression
Instructions and samples are available at : Code examples.

Massive data handling (Chunks)

The queries which are intended to retrieve massive volume of data, returns the data in Chunks i.e. the data is divided to few chunks of data. The number of chunks returned, is depending on the amount of data returned by the query.
The methods returning chunks, receives timestamp and number of chunk as parameters.
The query retrieves all data with update timestamp equal or higher than the timestamp parameter and set the data in 100 records chunks. The service will return the chunk number requested in the chunk number parameter provided to the query.
These services, using the chunks mechanism, should be operated as follows:

1. Call the service with a timestamp and the value '1' (One) as chunk number parameter.
2. Receive the first chunk from the service.
3. Check if the "Last chunk" flag in the returned structure is checked.
4. If the "Last chunk" flag in on, the service has transferred all the data retrieved.
5. If the "Last chunk" flag is off, continue to call the service with the consequent chunk number '2' (Two) to receive the next data chunk.
6. Continue with step 5 , with consequent chunk numbers until the value of the "Last Chunk" field is True.

The number of records in the last chunk will be between 0 and 99, depending on the quantity of records retrieved by the service.

Code samples

Code examples

Versions update log

Changes history