Getting Started

The Domec API is organized around REST.

Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code).

JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit the production networks and incur no cost.

In this section:

Content Negotiation
In the Hypertext Transfer Protocol (HTTP) specification, content negotiation is the mechanism that is used, when facing the ability to serve several equivalent contents for a given URI, to provide the best suited one to the final user. The determination of the best suited content is made through one of three mechanisms: specific HTTP headers by the client (server-driven negotiation) the 300 Multiple Choices or 406 Not Acceptable HTTP response codes by the server (agent-driven negotiation) a cache (transparent negotiation) Server-driven negotiation In this kind of negotiation, the browser (or any other kind of agent) sends several HTTP headers along with the URI.
More...
Transaction Receipt
Transaction receipt is the digital transposition of the classic fiscal receipt that is issued for every in-store sale. In the case that the sale is issued through a digital channel (e.g. e-commerce applications) the transaction receipt is the same as the order that get confirmed by the user at checkout. The Domec API platform defines a data structure which reproduce the fiscal receipt in the form of a json data structure.
More...
HTTP Status Codes
Domec uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Domec’s servers (these are rare we hope). Not all errors map cleanly onto HTTP response codes, however.
More...
Errors
Cross Services Code Property Description 0001 InvalidCampaignID Invalid Campaign ID has been provided 0002 ExpiredCampaign The Campaign is expired 0003 InvalidShopID Unable to find the Shop with the ID provided in input 0004 InvalidTerminalID Unable to find the Thermina with the ID provided in input 0005 InvalidServiceType Unable to process different services in the same call 0006 CatalogNotFound Can't find any catalog for the provided campaign 0007 ProductNotFound The provided product code cannot be found 0008 InvalidCompleteCode Syntax Error!
More...
Idempotent Requests
The Domec API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a charge fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single charge is created. To perform an idempotent request, provide an additional IdempotencyKey element to the request parameters. How you create unique keys is completely up to you.
More...
Metadata
Domec API expose some methods and endpoints which receives a Transaction Receipt objects in the input. The Transaction Receipt object has a metadata parameter. You can use this parameter to attach key-value data coming from your system. Metadata is useful for storing additional, structured information on an object. As an example, you could store your order unique identifier from your system on a receipt object. Metadata is not used by Domec (e.
More...
Pagination
All top-level API resources have support for bulk fetches via “list” API methods. For instance you can list transactions, list cards, and list rewards. These list API methods share a common structure, taking at least these three parameters: limit, skip, and take. Domec utilizes cursor-based pagination via the skip and take parameters. Both take an existing number value (see below). The take parameter returns objects created after the named object, in descending chronological order.
More...
Transaction IDs
Each API request has an associated request identifier. You can find this value in the response body, under transactionID. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution. { "serialNumber": "0280091541240100213315710822995526", "webSerialNumber": "", "properties": [], "transactionID": 95806, "cardStatus": "Active", "expiryDate": "2020-12-31T00:00:00", "balance": { "itemCollection": [ { "itemCode": "ABB01", "itemName": "Cappuccino", "itemCount": 0 }, { "itemCode": "ABB02", "itemName": "Cornetto", "
More...
Versioning
Domec REST services uses an API versioning configuration that is compliant with the versioning semantics outlined by the Microsoft REST Guidelines. When we make backwards-compatible changes to the API, we simply upgrade our servers. The current version is v1 (You can of course use it as v1.0). When we make backwards-incompatible changes to the API, we use the url-versioning scheme. This means that you will find a new version of the api endpoint available for the call.
More...