File Exchange

Exchanging data between partner and Koshelek

Main Principles

Sequence of interaction between a partner and Koshelek 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 Koshelek SFTP server.
• Koshelek server — the Koshelek 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:

<partner name>_clients_<date>.csv.zip

where:

• <Partner name> — name of the partner agreed by Koshelek (without whitespaces).
• <date> — date of the registry creation in format YYYYMMDD.

For example:

PartnerName_clients_20190131.csv.zip

The file consists of the following fields (in the specified order):

1. card_number — loyalty card number (string, up to 50 characters).
2. barcode — associated barcode number (string, up to 50 characters).
3. date— card issue date (string in format YYYYMMDD).
4. first_name — cardholder’s name (string, up to 50 characters).
5. last_name — cardholder’s surname (string, up to 50 characters).
6. patronymic_name — cardholder’s patronymic (string, up to 50 characters).
7. phone — cardholder’s phone number in MSISDN format (without the + prefix, for example: 79111111111).
8. email — cardholder’s email address (string, up to 50 characters).
9. sex — cardholder’s gender (string of one character: m or f).
10. birthday — cardholder’s date of birth (string in format YYYYMMDD).
11. bonus_balance — current bonus balance (integer).
12. discount — current discount amount (integer).
13. sum — amount of savings on the card (integer).
14. status — current card status (string; possible values: active or blocked).

Example of file content:

<header, ignored>
1120000029201582;1120000029201582;20180121;John;Smith;;79111111111;box@mail.dom;m;;2000;10;5000;active
1120000029201583;1120000029201583;20180122;Smith;Johnson;;79111111112;box2@mail.dom;m;;2000;10;5000;active

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:

new_<partner name>_clients_<date>.csv.zip

where:

• <Partner name> — name of the partner agreed by Koshelek (without whitespaces).
• <date> — date of the registry creation in format YYYYMMDD.

For example:

new_PartnerName_20190131.csv.zip

The file consists of the following fields (in the specified order):

1. card_number — loyalty card number (string, up to 50 characters).
2. barcode — associated barcode number (string, up to 50 characters).

Example of file content:

<header, ignored>
1120000029201582;1120000029201582
1120000029201583;1120000029201583

3. Registry of Loyalty Cards Issued by Koshelek

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:

from_koshelek_<date>.csv.zip

where:

• <date> — date of the registry creation in format YYYY-MM-DD.

For example:

from_koshelek_2019-01-31.csv.zip

The file consists of the following fields (in the specified order):

1. card_number — loyalty card number (string, up to 50 characters).
2. barcode — associated barcode number (string, up to 50 characters).
3. first_name — cardholder’s name (string, up to 50 characters).
4. last_name — cardholder’s surname (string, up to 50 characters).
5. patronymic_name — cardholder’s patronymic (string, up to 50 characters).
6. phone — cardholder’s phone number in MSISDN format (without the + prefix, for example: 79111111111).
7. email — cardholder’s email address (string, up to 50 characters).
8. sex — cardholder’s gender (string of one character: m or f).
9. birthday — cardholder’s date of birth (string in format YYYYMMDD).

Example of file content:

<header, ignored>
1120000029201582;1120000029201582;John;Smith;;79111111111;box@mail.dom;m;20000101
1120000029201583;1120000029201583;Smith;Johnson;;79111111112;box2@mail.dom;m;20000102