eKasa Spec

Version: v1.7
Contact: integrace@dotypay.com

Overview

Objective

The purpose of this document is to provide POS with a single API to communicate with PPEKK.

Glossary

Term	Description
POS	Point of Sale. This is the cash register, AKA Sale system. This term may refer to the hardware or the software of the POS.
PPEKK	POS
eKasa	Point of Interaction. This is the eKasa server.

General Requirements and Limitations

1. The eKasa must be able to listen to HTTP request (i.e., the eKasa is the server).
2. The POS is the client. It sends the request to the eKasa. The eKasa gets the response.
3. The request/response protocol between the POS and the eKasa will be based on HTTP.
4. The HTTP body will be in JSON format. This document will focus on the JSON messages that are sent in the HTTP body.

Communication PPEKK to CHDU

PPEKK and CHDU form one unit, the CHDU is connected directly to RS232 port of the printer therefore all print documents must pass through the CHDU device where they are saved. ECR/POS runs PPEKK as a system service and this service listens for HTTP requests of ECR/POS software. PPEKK then translates these requests to serial communication of CHDU.

Uploading data using GUI

On Android devices, starting with OS version 5.1, you can upload merchant data using application UI:

1. Put authentication and identification data into public Download directory. Data must be named ekasa_auth_data.xml and ekasa_ident_data.xml respectively.
2. In eKasa GUI, tap on the "Nahrať dáta do eKasa" in the side menu and then press the "Načítať údaje" button.
3. If the files were loaded, they must be unlocked by entering their password.
4. If the password was correct, successful activation message appears and the eKasa is ready to be used.

Consistency check mechanism

EKasa implementation holds all data on CHDU and it performs the consistency check process during startup and while it is running. When CHDU data are inconsistent (e.g., CHDU is missing of eKasa cannot read the certificate) eKasa does not allow any clients HTTP requests.

External system interface

External systems, e.g. POS/ECR, can communicate with eKasa implementation using the same HTTP protocol.

eKasa Protocol

By default, eKasa runs on port 13083 using plain HTTP protocol.

First request

If the eKasa runs on the same device as the POS app, it is recommended to check if the eKasa server is running.

To check if the server is running, it is recommended to try opening a network socket.

Examples for Android OS:

Checking that the server is reachable:

try {
    Socket socket = new Socket("127.0.0.1", 13083);
    socket.close();
} catch (IOException e) {
    return false; // not reachable
}
return true; // reachable

On Android API <= 22 you can check that the app itself is running:

final List<ActivityManager.RunningAppProcessInfo> procInfos = activityManager.getRunningAppProcesses();
if (procInfos != null) {
    for (final ActivityManager.RunningAppProcessInfo processInfo : procInfos) {
        if (processInfo.processName.equals(eKasaPackageName)) {
            return true;
        }
    }
}
return false;

If the app is not running, start it by sending the launch intent:

Intent startIntent = activity.getPackageManager().getLaunchIntentForPackage(eKasaPackageName);
startIntent.putExtra("HIDE_AFTER_INIT", true);
activity.startActivity();

When the app starts, it will hide automatically. When starting the app on older devices (Android 4), the user must minimize the app by pressing the hide button.

Mandatory HTTP Request Headers

Content-Type: application/json
Content-Length: 454
Accept-Charset: utf-8

HTTP Request Example

POST / http://192.168.0.100:13083/api/document/store http/1.1
Content-Type: application/json
Content-Length: 454
Accept-Charset: utf-8
{    "amount":247.23,
     "documentEntries" : [{
…
}]
....
} --> END POST

Mandatory HTTP Response Headers

Content-Type:application/json
Accept-Charset: utf-8
Content-Length: <the length of the JSON response string>

HTTP Response Example

HTTP/1.1 200 OK http://192.168.0.100:13083/api/document/store
Content-Type: application/json;charset=UTF-8
Content-Length: 1901
{    "document" : {
            …
            }
...
   "resultCode": 0
} <-- END HTTP

Default data type format in responses

• All date-time objects use format dd.MM.yyyy HH:mm:ss by default.
• Each response contains a resultCode object with the operation result. For more info see the [Result codes] section.

Result codes

The resultCode is the primary indicator of the outcome of an API call. Always check the resultCode to determine the type and validity of the response. Result code 0 means a successful operation, the list of possible codes is shown below.

Result	Result code	Result code description
0	OK	The request was successfully completed
100	PRINTER_NOT_READY	Printer is not ready to print The reason might be technical failure or overheat problem
101	PRINT_FAILED	Printer is unable to print the given data
102	PRINTER_NOT_CONNECTED	Printer isn't connected or turned on
103	COMMUNICATION_ERROR	Cannot communicate with the printer
104	PRINTER_NOT_SET	No printer is defined
105	NO_PAPER	The printer has no paper
106	PARTIAL_PRINT	Only part of the data have been printed. Please, see PartialPrintInfo for the reason. Then you can continue printing from specified offset.
200	CHDU_NOT_CONNECTED	CHDU has been disconnected
201	CHDU_IO_ERROR	Cannot communicate with CHDU device
202	CHDU_WRITE_LIMIT	Reached maximum written size
203	CHDU_RECORD_SIZE_LIMIT	Record exceeds max allowed size
300	BUSY	The app processes another request Try the request again later.
400	MERCHANT_WRONG_FORMAT	Merchant data contains wrongly formatted identification data fields See the errorMessage field in the response object for more info.
401	MERCHANT_DIFFERENT_DIC	The CHDU has been initialized with merchant with different DIC
402	MERCHANT_CERTIFICATE_ERROR	Cannot read merchant certificate
403	MERCHANT_WRONG_PASSWORD_OR_CORRUPTED_FILE	Merchant auth data password is wrong or the provided auth data are corrupted
404	MERCHANT_PARSE_ERROR	Cannot parse auth and identification data
405	MERCHANT_CERTIFICATE_EXPIRED	Merchant certificate is expired
500	NO_FIX_NEEDED	Last stored request is valid.
501	LAST_REQUEST_INVALID	Last stored request in CHDU is not valid. A fix is required.
502	INCORRECT_TIME	Either the time on the device is not correctly set or the document creation time is incorrect.
503	REQUEST_PARSE_ERROR	Cannot create the request message to SFS It usually means that the data in the CHDU are corrupted.
504	RESPONSE_PARSE_ERROR	Cannot create the response message from SFS It usually means that the data in the CHDU are corrupted.
505	NOTHING_TO_PRINT	When the document to print is null
506	NOT_FOUND	The requested document wasn't found
507	DOCUMENT_NOT_PRINTED	The document was successfully stored, but not printed due to a printer error See the printer error code.
508	LAST_DOCUMENT_NOT_PRINTED	Last stored document must be printed first
600	SFS_COMMUNICATION_ERROR	Cannot communicate with the SFS
601	REQUEST_ALREADY_SENT	Returned when the document has been already sent to the SFS
602	VERIFICATION_ERROR	Request or response data cannot be verified.
700	MALFORMED_INPUT	The request has invalid JSON structure
701	INVALID_INPUT	The request validation failed See the errorMessage field in the response object for more info.
-1	UNKNOWN_ERROR	A generic undocumented error See the errorMessage field in the response object for more info.

API Endpoints

Class	HTTP request	Description
CHDUApi	GET /api/chduinfo	Get CHDU params
CashApi	POST /api/cash	Cash deposit/withdraw
DocumentApi	POST /api/document/get	Get document
DocumentApi	POST /api/document/get/offline	Get offline documents
DocumentApi	POST /api/document/print	Print document which is waiting to be printed
DocumentApi	POST /api/document/send/offline	Send offline data
DocumentApi	POST /api/document/store	Store document
DocumentApi	POST /api/document/update	Update stuck document data
DrawerApi	POST /api/drawer/open	Open cash drawer
ImageApi	POST /api/image/preview	Preview merchant logo
ImageApi	POST /api/image/store	Store merchant logo
LocationApi	GET /api/location/get	Get last location
LocationApi	POST /api/location/update	Update location
MerchantApi	POST /api/merchant/get	Get merchant
MerchantApi	GET /api/merchant/status	Get merchant status
MerchantApi	POST /api/image/preview	Preview merchant logo
MerchantApi	POST /api/image/store	Store merchant logo
MerchantApi	POST /api/merchant/store	Store merchant
PrintApi	POST /api/document/print	Print document which is waiting to be printed
PrintApi	POST /api/print	Print string
PrinterApi	GET /api/printer	Get printer params
ReportApi	GET /api/report/offline/oldest	Get oldest offline record
ReportApi	POST /api/report/offline	Get offline report
SettingsApi	GET /api/settings/get	Get settings
SettingsApi	PUT /api/settings/store	Save settings
StatusApi	GET /api/status/get	Get app status
VersionApi	GET /api/version	Get version

Models

• AppSettings
• BlockStorageInfo
• Cash
• CashRequest
• CashResponse
• CertificateStatusResponse
• ChduInfoResponse
• ChduParams
• ConnectedPrinterParams
• Customer
• DocumentByExternalId
• DocumentByInternalId
• DocumentByOkp
• DocumentByPkp
• DocumentBySequenceId
• DocumentByUUID
• DocumentItem
• DocumentReceiptItem
• DocumentResponse
• EkasaError
• EkasaStatus
• EkasaWarning
• ErrorResponse
• FixDocument
• FixDocumentItem
• FixLocation
• GenericResponse
• GetDocumentRequest
• GetMerchantRequest
• GetOfflineDocumentsRequest
• Gps
• Location
• LocationResponse
• LogoPreviewResponse
• Merchant
• MerchantByCashRegisterCode
• MerchantBySequenceId
• MerchantCertificateStatus
• MerchantResponse
• OfflineDocumentsFilter
• OfflineReportResponse
• OpenDrawerRequest
• OrganizationUnit
• PartialPrintInfo
• PhysicalAddress
• PreviewImageRequest
• PrintStringRequest
• Printer
• PrinterResponse
• RawResponse
• ResponseDocument
• ResponseMeta
• Seller
• SendOfflineRequest
• SettingsResponse
• SpecialRegulationChange
• StatusResponse
• StoreDocumentRequest
• StoreImageRequest
• StoreMerchantRequest
• StoreSettingsRequest
• UpdateDocumentRequest
• UpdateLocationRequest
• VatRateSum
• VersionData
• VersionResponse