gurado REST API Documentation

(1)

gurado REST API Documentation

gurado Rest API operations

2.1 Vouchers

Look up a voucher Sale a voucher Redeem a voucher

List voucher transactions Generate a voucher List all vouchers

Convert old to new voucher

The gurado REST API uses HTTP verbs and a RESTful endpoint structure.

Request and Response are formatted as JSON or XML format.

The gurado REST API is supported in live environment and generally used in EPOS Terminal System where vouchers are sold and redeemed.

The following endpoints address our live environment:

https://www.gurado.de/{shop-name}/

Where {shop-name} is your gurado shop name.

A complete REST operation is formed by combining an HTTP method (or

(2)

“verb”) with the full URI to the resource you’re addressing.

For example, here is the operation to get voucher information:

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/{code}

Where v1.0 is the current version of this api and in future can be changed with latest version

Authentication & Headers:

With each API call, you’ll need to set request headers, including Consumer key & consumer secret which is supplied by gurado system. Use X-GURADO- CONSUMER-KEY variable to provide Consumer key & X-GURADO-

CONSUMER-SECRET variable to provide the Consumer secret to gurado system as your Auth credentials.

gurado Rest API operations:

Here are the available gurado REST API operations:

1. Look up a voucher: Get information of a particular voucher by using voucher code or external ID

Method: GET Urls:

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/{code}

Or

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ext- {externalId}

Where {code} is voucher code and {externalId} is external ID of a voucher used in Consumer system.

Request:

Pass the voucher code or external ID in the endpoint.

Response:

Returns a Voucher object in JSON or XML format.

Property Type Description Value details

code string Voucher Code Characters,

Numbers and “-” are allowed externalId string Voucher External

ID Numbers

(3)

pin int Secure Pin 4 digit number

currencyCode string Currency code Currency code like EUR, CHF

type string Voucher Type

GIFT_VOUCHER, TICKET, COUPON, SEASON_TICKET, MULTI_SCAN_TICKET, TIME_BOUND_TICKET, NO_INFORMATION

balance double Balance of

Voucher 0 - 99999999,99 numberOfUsesAllowed int

Total number of voucher usage allowed

0 – 999, NOT_APPLICABLE

numberOfUsesRemaining int

Total number of voucher usage remaining

0 - 999, NOT_APPLICABLE validFromDate date Valid From Date YYYY-MM-DD HH:MM:SS,

NO_INFORMATION validToDate date Valid To Date YYYY-MM-DD HH:MM:SS,

NO_INFORMATION isOldVoucher int Is Old Voucher 1 – OLD, 0 - NEW

status string Status of

Voucher

ACTIVE, INACTIVE, PENDING, NO_INFORMATION

creationDate date Voucher creation date

YYYY-MM-DD HH:MM:SS, NO_INFORMATION soldBy string Transaction by ONLINE_SHOP, IN_STORE,

NO_INFORMATION orderNumber int Order Number 10 digit number invoiceNumber int Invoice Number 10 digit number receiptNumber int Receipt Number 10 digit number paymentMethod string Payment Method Characters

product object Product object Product details object recipient object Recipient object Recipient details object

Product Object:

(4)

name string Product Name Max. 255 characters price double Product price 0 - 99999999,99 taxRate double Tax rate 0 - 100

externalSku string

External Sku is a unique identification code of a Product

Max. 50 characters usually alphanumeric

Recipient Object:

name string Recipient Name

Max. 50 characters alphanumeric

email string Recipient Email

Address

[email protected]

address object Address Object Address details object

Address Object:

street string Street Max. 100 characters

postcode string Postcode Max. 10 characters

city string City Name Max. 20 characters

country string Country Name Max. 20 characters

(5)

EXAMPLE:

REQUEST:

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ABCD-EFGH- IJKL

Or

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ext-12345

Request Sample:

curl -v -X GET https://www.gurado.de/{shop-

name}/restapi/v1.0/vouchers/{code} or ext-{externalId} \ -H "ACCEPT:application/json" \

-H "X-GURADO-CONSUMER-KEY: <Key-Token>" \ -H "X-GURADO-CONSUMER-SECRET: <Secret-Token>"

RESPONSE JSON format:

{

"voucher":{

"code":"ABCD-EFGH-IJKL", "externalId":"12345", "pin":"1234",

"currencyCode":"EUR", "type":"GIFT_VOUCHER", "balance":20.00,

"numberOfUsesAllowed":"NOT_APPLICABLE", "numberOfUsesRemaining":"NOT_APPLICABLE", "validFromDate":"2015-01-01 01:00:00",

"validToDate":"2030-12-31 00:00:00", "isOldVoucher":0,

"status":"ACTIVE",

"creationDate":"2015-01-01 01:00:00", "soldBy": "ONLINE_SHOP"

"orderNumber": "1000000001"

"invoiceNumber": "1000000001"

"receiptNumber": "NOT_APPLICABLE"

"paymentMethod": "PAYPAL_STANDARD"

"product":{

(6)

"name":"Gift Voucher", "price":20,

"taxRate":19,

"externalSku":"GV123"

},

"recipient":{

"name":"Georg Dirk",

"email":”[email protected]”, "address":{

"street":”Wittbräucker Str. 32”, "postcode":44287,

"city":”Dortmund”, "country":”Germany”

} } } }

XML format:

<?xml version="1.0" encoding="utf-8"?>

<xml>

<type>GIFT_VOUCHER</type>

<numberOfUsesAllowed>NOT_APPLICABLE</numberOfUsesAllowed>

<numberOfUsesRemaining>NOT_APPLICABLE</numberOfUsesRemaining>

<status>ACTIVE</status>

<soldBy>ONLINE_SHOP</soldBy>

<receiptNumber>NOT_APPLICABLE</receiptNumber>

(7)

<paymentMethod>PAYPAL_STANDARD</paymentMethod>

<name>Gift Voucher</name>

</product>

<name>Georg Dirk</name>

<email>[email protected]</email>

<street>Wittbräucker Str. 32</street>

<city>Dortmund</city>

<country>Germany</country>

</address>

</recipient>

</voucher>

</xml>

2. Sale a voucher

: Sale a Voucher by using voucher code or external ID Method: PUT

Urls:

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/{code}/sale Or

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ext- {externalId}/sale

Request:

(8)

externalProductSku string

External Sku is a unique

identification code of Product

Max. 50 characters usually

alphanumeric

amount double Voucher sale value 0 - 99999999,99

transactionDate date Transaction Date YYYY-MM-DD HH:MM:SS

Response:

Property type Description Value details

messageStatus string Status of sale

transaction SUCCESS, FAILURE

messageCode string

Unique code to identify

transaction message

VOUCHER_SOLD_SUCCESSFULLY, VOUCHER_SALE_FAILED

messageDescription string

Details of transaction message

Text

Request Sample:

curl -v https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/{code} or ext-{externalId}/sale \

-H "ACCEPT:application/json" \

-H "X-GURADO-CONSUMER-KEY: <Key-Token>" \

-H "X-GURADO-CONSUMER-SECRET: <Secret-Token>" \

-d externalProductSku=1245 -d amount=20.00 -d transactionDate=2015-01-01 01:00:00

3. Redeem a voucher

: Redeem a Voucher by using voucher code or external ID with

(9)

Method: PUT Urls:

https://www.gurado.de/{shop-

name}/restapi/v1.0/vouchers/{code}/redeem

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ext- {externalId}/redeem

Request:

Response:

messageStatus string Status of sale

transaction SUCCESS, FAILURE

messageCode string

Unique code to identify transaction message

VOUCHER_REDEEMED_SUCCESSFULLY, VOUCHER_REDEMPTION_FAILED

Text

Request Sample:

(10)

curl -v https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/{code} or ext-{externalId}/redeem \

-H "X-GURADO-CONSUMER-SECRET: <Secret-Token>" \ -d amount=10.00 -d transactionDate=2015-03-02 01:00:59

4. List voucher transactions

: Get List of voucher transaction by using voucher code or external ID with

Method: GET Urls :

name}/restapi/v1.0/vouchers/{code}/transactions

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ext- {externalId}/transactions

Request:

Pass the voucher code or external ID in the endpoint.

Response:

Returns a Voucher object in JSON or XML format.

code string Voucher Code

Characters,

Numbers and “-” are allowed

externalId string Voucher External

ID Numbers

(11)

status string Status of Voucher

ACTIVE, INACTIVE, PENDING,

NO_INFORMATION creationDate date Transaction by ONLINE_SHOP, IN_STORE,

NO_INFORMATION

soldBy string Order Number 10 digit number

orderNumber int Invoice Number 10 digit number invoiceNumber int Receipt Number 10 digit number receiptNumber int Payment Method Characters

paymentMethod string Product object Product details object product object Recipient object Recipient details object

recipient object Transactions

object

List of voucher transaction history

transactions

Product Object:

(12)

name string Product Name Max. 255 characters

price double Product price 0 - 99999999,99

taxRate double Tax rate 0 - 100

externalSku string

identification code of a Product

alphanumeric

Recipient Object:

name string Recipient Name Max. 50 characters

alphanumeric

Address [email protected]

Address Object:

(13)

Transaction Object:

outlet string

Name of outlet that performed transaction

Max. 100 characters

action string Transaction action SALE, REDEEM,

CORRECT

amount double Transaction

amount 0 - 99999999,99

date date Date of transaction

YYYY-MM-DD HH:MM:SS,

NO_INFORMATION

orderNumber int

order number if voucher purchased online

Max. 10 digit number receiptNumber int

receipt number if voucher purchased in store

Max. 10 digit number externalReceiptNumber string

External receipt number generated by consumer

Max. 50 characters

EXAMPLE:

REQUEST

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ABCD-EFGH- IJKL/transactions

or

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ext- 12345/transactions

Request Sample:

curl -v -X GET https://www.gurado.de/{shop-

name}/restapi/v1.0/vouchers/{code} or ext-{externalId}/transactions \ -H "ACCEPT:application/json" \

(14)

RESPONSE JSON format:

{

"voucher":{

"code":"ABCD-EFGH-IJKL", "externalId":"12345", "pin":"1234",

"currencyCode":"EUR", "type":"GIFT_VOUCHER", "balance":20.00,

"numberOfUsesAllowed":"NOT_APPLICABLE", "numberOfUsesRemaining":"NOT_APPLICABLE", "validFromDate":"2015-01-01 01:00:00",

"validToDate":"2030-12-31 00:00:00", "isOldVoucher":0,

"status":"ACTIVE",

"creationDate":"2015-01-01 01:00:00", "soldBy": "ONLINE_SHOP"

"orderNumber": "1000000001"

"invoiceNumber": "1000000001"

"receiptNumber": "NOT_APPLICABLE"

"paymentMethod": "PAYPAL_STANDARD"

"product":{

"name":"Gift Voucher", "price":20,

"taxRate":19,

"externalSku":"GV123"

},

"recipient":{

"name":"Georg Dirk",

"email":”[email protected]”, "address":{

"street":”Wittbräucker Str. 32”, "postcode":44287,

"city":”Dortmund”, "country":”Germany”

} },

"transactions":[

(15)

{

"outlet":"gurado", "action":"SALE", "amount":20,

"date":"2015-01-01 01:00:00", "orderNumber":"NOT_APPLICABLE", "receiptNumber":"10000001",

"externalReceiptNumber":"NOT_APPLICABLE"

}, {

"outlet":"gurado", "action":"REDEEM", "amount":18,

"date":"2015-01-01 02:00:00", "orderNumber":"NOT_APPLICABLE", "receiptNumber":"10000002",

"externalReceiptNumber":"NOT_APPLICABLE"

} ] } }

XML format:

<?xml version="1.0" encoding="utf-8"?>

<xml>

<type>GIFT_VOUCHER</type>

<numberOfUsesAllowed>NOT_APPLICABLE</numberOfUsesAllowed>

<numberOfUsesRemaining>NOT_APPLICABLE</numberOfUsesRemaining>

(16)

<status>ACTIVE</status>

<soldBy>ONLINE_SHOP</soldBy>

<receiptNumber>NOT_APPLICABLE</receiptNumber>

<paymentMethod>PAYPAL_STANDARD</paymentMethod>

<name>Gift Voucher</name>

</product>

<name>Georg Dirk</name>

<email>[email protected]</email>

<street>Wittbräucker Str. 32</street>

<city>Dortmund</city>

<country>Germany</country>

</address>

</recipient>

<outlet>gurado</outlet>

<orderNumber>NOT_APPLICABLE</orderNumber>

<externalReceiptNumber>NOT_APPLICABLE</externalReceiptNumber>

</transaction>

<outlet>gurado</outlet>

<action>REDEEM</action>

<orderNumber>NOT_APPLICABLE</orderNumber>

(17)

<externalReceiptNumber>NOT_APPLICABLE</externalReceiptNumber>

</transaction>

</transactions>

</voucher>

</xml>

5. Generate and sale a voucher

: Generate and sale a Voucher Method: POST

Urls:

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers

Request:

externalProductSku string

identification code of Product

alphanumeric

Response:

Property type Description Value details

messageStatus string

Status of generate transaction

SUCCESS, FAILURE

messageCode string

AUTO_VOUCHER_GENERATION_NOT_ALLOWED, INVALID_AMOUNT,

UNABLE_TO_GENERATE_NEW_VOUCHER, PRODUCT_NOT_FOUND,

VOUCHER_SALE_FAILED

(18)

Text

Request Sample:

curl -v https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers \ -H "ACCEPT:application/json" \

-d externalProductSku=1245 -d amount=20.00 -d transactionDate=2015-01-01 01:00:00

6. List all vouchers: Get information of all vouchers with pagination Method: GET

Urls:

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers

Request:

fromDate date From Date (url

encoded)

YYYY-MM-DD HH:MM:SS

Default all vouchers

toDate date To Date (url

encoded)

YYYY-MM-DD HH:MM:SS

Default all vouchers

page int Current page

number Default 1

pageSize int Number of

vouchers per page

Default 20, Max 100 vouchers per page

Response:

Returns a list of Voucher objects in JSON or XML format.

(19)

code string Voucher Code Characters,

Numbers and “-” are allowed externalId string Voucher External

ID Numbers

status string Status of

Voucher

ACTIVE, INACTIVE, PENDING, NO_INFORMATION

creationDate date Voucher creation date

YYYY-MM-DD HH:MM:SS, NO_INFORMATION soldBy string Transaction by ONLINE_SHOP, IN_STORE,

NO_INFORMATION orderNumber int Order Number 10 digit number invoiceNumber int Invoice Number 10 digit number receiptNumber int Receipt Number 10 digit number paymentMethod string Payment Method Characters

product object Product object Product details object

(20)

recipient object Recipient object Recipient details object

Product Object:

name string Product Name Max. 255 characters price double Product price 0 - 99999999,99 taxRate double Tax Rate 0 - 100

externalSku string

External Sku is a unique identification code of a Product

Max. 50 characters usually alphanumeric

Recipient Object:

name string Recipient Name

Max. 50 characters alphanumeric

Address

[email protected]

Address Object:

(21)

Paging Object:

total int Total Vouchers 0 - 999

perPage int Vouchers per Page 0 - 999 currentPage int Current Page 0 - 999

lastPage int Last Page 0 - 999

from int Vouchers From 0 - 999

to int Vouchers To 0 - 999

EXAMPLE:

REQUEST:

name}/restapi/v1.0/vouchers?page=1&pageSize=20

Request Sample:

curl -v -X GET "https://www.gurado.de/{shop-

name}/restapi/v1.0/vouchers?page=<Current-Page >&pageSize=<Page-Size>" \ -H "ACCEPT:application/json" \

(22)

7. Convert old to new voucher

: Convert old to new voucher by using voucher code or external ID

Method: PUT Urls:

https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/{code}/convert https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/ext-

{externalId}/convert

Request:

newVoucherCode string New voucher code Alphanumeric

amount double Voucher correction

value 0 - 99999999,99

Response:

messageStatus string Status of

conversion SUCCESS, FAILURE

messageCode string

VOUCHER_CONVERTED_SUCCESSFULLY, VOUCHER_CONVERSION_FAILED

(23)

Text

Request Sample:

curl -v https://www.gurado.de/{shop-name}/restapi/v1.0/vouchers/{code} or ext-{externalId}/convert \

-d newVoucherCode=XXXXX-XXXXX -d amount=10.00 -d transactionDate=2015- 03-02 01:00:59

gurado REST API Documentation