Server for
Point of sale

Server for Point Of Sale is a Web Service, available 24/7/365, which keeps a data of POS terminals (cash registers) in a central place and collects cash transactions

Explains urls, HTTP headers, status codes, way of returning error codes, caching and data consistancy.

Before reading this article we recommend you to read Terms, Security and Error handling.

The background protocol is regular HTTP. Follow regular REST convention to understand API architecture. Here is a few important points you must know:

  • Response body is returned according to Accept header when no error occurs. It should be “application/json” for JSON and “application/javascript” for JSONP.
  • List of all available url’s for data exchange with description and code samples can be found at JSON-REST Reference .
  • And don’t forget to declare Content-Type: application/json when sending data to the server.

Url naming conventions

General format of every url is[options]


  • will be provided to you by support team
  • version is a number of current api version, you can find this number by visiting, and get all the info (documentation, examples and libraries) about it at For instance if version is 15, then the url will look like[/options], the info about it is reacheable at
  • collection-name is the name of entity, for instance all products can be found by url
  • options might be
    • /identifier
      to reach particular entity. for instance to reach product with identifier “0-1A9E” you use
    • -diff/from/to
      to discover, what has been changed on the server. for instance, if you want to know which products have been deleted, created or modified between 100 and 200 you use . If you are interested what is 100 and 200 – read Synchronization and Caching
    • /identifier/images
      to see which images are attached to a particular entity. for instance will show list of all images for product with id 0-1A9E
    • ?firstResult=0&maxResults=30&orderBy=fieldName&orderDesc=false&like=substring to be able to narrow output results. Each parameter is optional. Some parameters might not work under some urls. There can be some more parameters

This is just a convention, and some urls don’t follow it.

Other notes:

  • Words are separated with hyphens (‘-‘) and lower case:
  • GET, DELETE, PUT http methods are allowed for
  • POST to creates an entity
  • This convention was taken from


Most of the URLs requires authentication. Basic authentication is used. Use “Authorization” header. Value is word “Basic ” and base64 encoded string. The string depends on your role:

  • For role ACTIVATION the string is:
  • For role SELLER_ADMIN the string is:

Error handling

For simple json exceptions:


1 {"error":"SomeSimpleJsonException"}

For detailed json exceptions:

{ "details":{ "identifier":"ID-1", "entityName":"MyEntity" }, "error":"SomeDetailedJsonException" }

1 2 3 4 5 6 7 { "details":{ "identifier":"ID-1", "entityName":"MyEntity" }, "error":"SomeDetailedJsonException" }

For special ValueNotValidJsonException:

{ "details":[ { "code":"SPECIFIC_ERROR_CODE", "field":"name", "message":"Some message.", "params":{ "actualValue":"invalidValue", "someParam1":"1", "someParam2":"32" } } ], "error":"ValueNotValidJsonException" }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "details":[ { "code":"SPECIFIC_ERROR_CODE", "field":"name", "message":"Some message.", "params":{ "actualValue":"invalidValue", "someParam1":"1", "someParam2":"32" } } ], "error":"ValueNotValidJsonException" }

For UnprocessableJsonException, InconsistentDataJsonException and ForbiddenJsonException:

{ "code":"SPECIFIC_ERROR_CODE", "details":{ "message":"Some message" }, "error":"SomeSpecialJsonException" }

1 2 3 4 5 6 7 { "code":"SPECIFIC_ERROR_CODE", "details":{ "message":"Some message" }, "error":"SomeSpecialJsonException" }

The field “error” contains name of json exception.

The field “code” contains specific code of error. It can be used for localization and so on.

List of all JsonExceptions and types of error (codes) presented in the here.


Some GET methods support ETag header. When returning data they return seller version inside ETag. Seller version and principles are described at Synchronization and Caching page. Later you can provide If-Match to the methods so they may return HTTP status code 304 and no body, Which means the data was not modified since the seller version specified in ETag.

Date & time

All data & time is always in UTC.

Data consistancy

If your role is ACTIVATION then POST, PUT, DELETE methods require you to provide latest seller version (to make sure the version is actually latest). Provide it in If-Match header. If you want to know more about Data consistancy, read Synchronization and Caching page.

© 2015-2023 Server For Pos. All rights reserved.