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

fuelprovision

the value of the commission to be calculated from the discounted price for 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

 

 

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.

currency

String

ISO 4217 currency code.

id

String

The unique ID of the purchase, in the partner’s system.

tally

Array

The purchased products.

 

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.

 

 

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.