API for Data Forwarding
SUBMIT PURCHASE DATA
Please follow this technical information for sending purchase data, that generated at buying using with bercode.
The implementation of the service is using Representational State Transfer (REST) architecture (http://en.wikipedia.org/wiki/Representational_state_transfer), and JavaScript Object Notation (JSON) (http://json.org) data transfer protocol. The service is easy to use with different development platforms and languages with REST and JSON.
You can query the code validity, the provided discount, and the commission rate, by giving the bercode used for the purchase.
It can be retrieved by HTTP GET calls at https://www.bercode.com/api/checkcode/[store]/[bercode] link, where the [store] is the Api ID of the merchant given on https://www.bercode.com page, where the purchase was, and the [bercode] is the value of the bercode, that you want to check. You can use HTTP Basic authentication for the login, with the Api ID and Api Key data, that you can get at the Purchase data – Purchase settings page of https://www.bercode.com site.
For example: https://www.bercode.com/api/checkcode/554732/348000419064329953
The answer contains the data that belongs to the [bercode] in JSON format:
|
Parameter |
Explanation |
|
error |
error code |
|
errortext |
description of the error, in case of error |
|
fueldiscount |
discount rate based on bercode for fuel at normal price |
|
specialfueldiscount |
discount rate based on bercode for fuel at special price |
|
discountpercent |
discount rate based on bercode at normal price |
|
specialdiscountpercent |
discount rate based on bercode at special price |
|
provisionpercent |
the value of the commission to be calculated from the discounted price |
|
specialprovisionpercent |
the value of the commission to be calculated from the discounted price in case of already discounted products |
|
fuelprovision |
the value of the commission to be calculated from the discounted price for fuel |
|
specialfuelprovision |
the value of the commission to be calculated from the discounted price for already discounted fuel |
|
discountunit |
Quantity unit of fuel discount. |
If the value of error is 0, then the Bercode is appropriate, and the discount can be provided.
If the code is wrong, then the value of error will be the following:
|
error |
errortext |
|
1 |
Unknown bercode |
|
2 |
Wrong bercode level |
|
3 |
The bercode is expired |
|
4 |
The bercode issuer is not authorized at the merchant. |
For example, the answer is: {"response":{"discountunit":"HUF/l","discountpercent":10,"specialdiscountpercent":5,"fueldiscount":8,"specialfueldiscount":4,"fuelprovision":"3.00","provisionpercent":3,"error":0,"errortext":""},"statusCode":200}
The given standard HTTP response codes for requests:
|
HTTP Status Code |
Explanation |
|
200 |
Data submit is okay. |
|
400 |
The request could not be understood by the server due to malformed syntax. |
|
401 |
The request requires user authentication. |
|
500 |
The server encountered an unexpected condition which prevented it from fulfilling the request. |
The summarized purchase data can be transferred via HTTP PUT calls to https://www.bercode.com/api/provision. You can use HTTP Basic authentication for the login, with the Api ID and Api Key data, that you can get at the Purchase data – Purchase settings page of https://www.bercode.com site. One PUT call can contains more object in one JSON array format, in the body of the PUT call. The MIME type of the PUT call must be application/json.
|
Description |
Type |
Explanation |
|
bercode |
String |
The value of the bercode used for the purchase. |
|
time |
String |
Purchase date and time in ISO8601 format. |
|
store |
String |
Merchant Api ID |
|
cr |
String |
The cash register code in the partner’s system, where the purchase was. It is optional. |
|
currency |
String |
ISO 4217 currency code. |
|
id |
String |
The unique ID of the purchase, in the partner’s system. |
|
tally |
Array |
Aggregated data of the purchased items. |
| items | Array | Detailed data of the purchased items. It is optional. |
The tally array contains the products data aggregated by rule parameter. If the purchase contains normal price products only, or special price products only, then the prices must be added together, and it must be given in one row in the tally array. If the purchase contains normal price products and special price products too, then the tally array contains two rows.
|
Description |
Type |
Explanation |
|
rule |
Integer |
Value can be 0 or 1 only. 0 = normal price, 1 = special price |
|
price |
Number |
The sum of the normal price of the products. |
|
discountprice |
Number |
The sum of the special price of the products. |
|
discountpercent |
Number |
Percentage value of discount. |
|
provision |
Number |
Amount of payable commission. |
|
quantity |
Number |
The quantity of the products. |
|
discountunit |
Number |
The unit of the discount. Value can be 1 or 2 only. 1 - %, 2 – unit received in checkcode function discountunit parameter. The quantity is required in case of 2. |
The items array contains the detailed data of the products. It is optional. Its value is deleted from the server after 45 days.
|
Description |
Type |
Explanation |
| item_serno |
Integer |
Lot number |
| item_id | String | Product identifier |
| item_name | String | Product name |
| quantity | Number | Quantity |
| unit_name | String | Packaging unit |
| unit_price | Number | Net unit price |
| vat | Number | Value added tax |
| item_amount | Number | Item total amount payable |
For example: {"bercode":"348123415093345678", "time":"2013-07-08T15:20:38Z", "store":"554732", "cr":"028", "currency":"HUF", "id":"79e242c0",
"tally":[{"rule":0, "price":2381, "discountprice":2000, "discountpercent":16, "discountunit":1, "provision":60}]}
In case of fuel and shop product purchase:
{"bercode":"348123415093345678", "time":"2013-07-08T15:20:38Z", "store":"554732", "cr":"028", "id":"79e242c0", "currency":"HUF",
"tally":[{"rule":0, "price":1000, "discountprice":900, "discountpercent":10, "provision":27, "discountunit":1},{"quantity":"20", "rule":"0", "price":6000, "discountprice":5840, "discountpercent":8, "provision":60, "discountunit":2}]}
The given standard HTTP response codes for requests:
|
HTTP Status Code |
Explanation |
|
201 |
Data request is okay. |
|
400 |
The request could not be understood by the server due to malformed syntax. |
|
401 |
The request requires user authentication. |
|
409 |
The given ID already exists. |
|
500 |
The server encountered an unexpected condition which prevented it from fulfilling the request. |
It is enough to send the purchase data for the settlement; the following two options are optional:
The submitted purchase data can be check via HTTP GET calls to https://www.bercode.com/api/provision/[id]. You must give the unique ID of the purchase as the [id].
For example: https://bercode.com/api/provision/79e242c0
The response to the request contains the data for the given [id] in JSON format.
The given standard HTTP response codes for requests:
|
HTTP Status Code |
Explanation |
|
201 |
Data request is okay. |
|
400 |
The request could not be understood by the server due to malformed syntax. |
|
401 |
The request requires user authentication. |
|
404 |
The given ID not exists. |
|
500 |
The server encountered an unexpected condition which prevented it from fulfilling the request. |
The submitted purchase data can be delete via HTTP DELETE calls to https://www.bercode.com/api/provision/[id]. You must give the unique ID of the purchase, that you want to delete, as the [id].
For example: https://edc.hu/api/provision/79e242c0
|
HTTP Status Code |
Explanation |
|
201 |
Data request is okay. |
|
400 |
The request could not be understood by the server due to malformed syntax. |
|
401 |
The request requires user authentication. |
|
404 |
The given ID not exists. |
|
500 |
The server encountered an unexpected condition which prevented it from fulfilling the request. |
You can use barcodes on the https://www.bercode.com/content/uploads/tesztvonalkodok.pdf page to test the process.