Files Exchanging
Exchanging data between partner and Cardsmobile
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:
Main Principles
Sequence of interaction between a partner and Cardsmobile is presented in the figure below.
where:
Partner's CRM system — the information system of a partner that issues its loyalty cards via the Koshelek app.
File storage — a file storage for data exchange and a sFTP server run by Cardsmobile.
Koshelek server — the Cardsmobile platform component that provides interaction with partners issuing loyalty cards in the Koshelek app and prepares reports and registries of issued cards.
The partner uploads its files to the in directory. Files created by the Koshelek server are uploaded to the out directory.
File Formats
1. Registry of Issued Loyalty Cards
The registry is transmitted by the partner with the specified frequency rate (at least once a day is recommended). The file must be named according to the following schema:
where:
<Partner name> — name of the partner agreed by Cardsmobile (without whitespaces).
<date> — date of the registry creation in format YYYYMMDD.
For example:
The file consists of the following fields (in the specified order):
card_number— loyalty card number (string, up to 50 characters).barcode— associated barcode number (string, up to 50 characters).date— card issue date (string in format YYYYMMDD).first_name— cardholder's name (string, up to 50 characters).last_name— cardholder's surname (string, up to 50 characters).patronymic_name— cardholder's patronymic (string, up to 50 characters).phone— cardholder's phone number in MSISDN format (without the+prefix, for example: 79111111111).email— cardholder's email address (string, up to 50 characters).sex— cardholder's gender (string of one character: m or f).birthday— cardholder's date of birth (string in format YYYYMMDD).bonus_balance— current bonus balance (integer).discount— current discount amount (integer).sum— amount of savings on the card (integer).status— current card status (string; possible values: active or blocked).
If the status field is not presented in the file or contains an empty value or a value that differs from active and blocked, the Cardsmobile platform defines the card status as active by default.
Example of file content:
2. Registry of Reserved Loyalty Card Numbers
The registry is transmitted by the partner as soon as it is required (to avoid emptying the set of numbers). The file must be named according to the following schema:
where:
<Partner name> — name of the partner agreed by Cardsmobile (without whitespaces).
<date> — date of the registry creation in format YYYYMMDD.
For example:
The file consists of the following fields (in the specified order):
card_number— loyalty card number (string, up to 50 characters).barcode— associated barcode number (string, up to 50 characters).
Example of file content:
3. Registry of Loyalty Cards Issued by Cardsmobile
The registry is transmitted by the Koshelek server daily. The file date is always equal to issue date of loyalty cards listed in the file. The file must be named according to the following schema:
where:
<date> — date of the registry creation in format YYYY-MM-DD.
For example:
The file consists of the following fields (in the specified order):
card_number— loyalty card number (string, up to 50 characters).barcode— associated barcode number (string, up to 50 characters).first_name— cardholder's name (string, up to 50 characters).last_name— cardholder's surname (string, up to 50 characters).patronymic_name— cardholder's patronymic (string, up to 50 characters).phone— cardholder's phone number in MSISDN format (without the+prefix, for example: 79111111111).email— cardholder's email address (string, up to 50 characters).sex— cardholder's gender (string of one character: m or f).birthday— cardholder's date of birth (string in format YYYYMMDD).
Example of file content:
If necessary (by agreement with the partner), additional fields may be added to the file at the end of field list.
In order to get information about loyalty cards issued for a partner in the Koshelek app quickly, it is recommended to download the registry of loyalty cards issued by Cardsmobile at least once a day.
Last updated
