Connection to API

Connection requirements

Documentation has moved

The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:

https://developers.koshelek.app/en/

Interaction Model

The API uses the RESTful model (all the data is transferred as JSON objects). The feature of this model is that a partner and Cardsmobile use two interfaces for the interaction:

• Push API — used by the partner to send push messages.

• Callback API — used by Cardsmobile to transmit information on push messages delivery and reading by recipient to the partner.

Partner and Cardsmobile interaction model

Connection Parameters

Push API

Push API is provided by the Cardsmobile host.

The following request parameters are provided for a partner in order to get access:

Parameter	Description
host:port	Address and port of the Cardsmobile host providing the API.
login:password	Username and password for API requests authorization.

Number of accounts is not restricted. Still, each account determines the following:

• partner whose clients will receive push messages.

• address of Callback API for sending the information on push messages delivery and reading status.

Callback API

The Callback API is provided by the partner host.

The partner must provide a "reverse" address that will be used by the Cardsmobile host to sent push messages status information.

API Requests Authorization

The HTTPS protocol is used. HTTP Basic Authentication (RFC 7617) mechanism should be used for API requests authorization. Credentials for authorization are transferred in the Authorization HTTP header.

Encoding Requirements

Both API requests and responses should use the UTF-8 encoding.

Response Codes

If the request is successfully processed, the Cardsmobile host returns an HTTP response containing the status code 200, and the body with a payload described in the request documentation.

HTTP code	Description
200	API request is successfully processed.

If an error occurred during the request processing, the host returns an HTTP response containing one of the status codes from the table below, and the error description as a JSON object in the body (the UTF-8 encoding is used):

HTTP code	Description
304	New request came earlier than expected.
400	Invalid request format.
401	Authorization error.
404	Requested data not found.

Examples of error description:

HTTP: 400

{
    "status": "BAD_REQUEST",        // HTTP status of the error
    "errors": [                     // array of errors
        "msisdn: size must be between 0 and 10000", // error description
        "subId: may not be null"
    ]
}

HTTP: 401

{
    "status": "UNAUTHORIZED",
    "errors": [
        "Auth token is invalid"
    ]
}