gurado REST API Documentation

Transcrição

1 gurado REST API Documentation Table of Contents: 1. Authentication & Headers 2. gurado Rest API operations 2.1 Vouchers Look up a voucher Sale a voucher Redeem a voucher List voucher s 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: 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: 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: Or {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. code Voucher Code externalid Voucher External ID Characters, Numbers and - are allowed Numbers

3 pin int Secure Pin 4 digit number currencycode Currency code Currency code like EUR, CHF type Voucher Type balance numberofusesallowed double int numberofusesremaining int Balance of Voucher Total number of voucher usage allowed Total number of voucher usage remaining validfromdate date Valid From Date validtodate date Valid To Date GIFT_VOUCHER, TICKET, COUPON, SEASON_TICKET, MULTI_SCAN_TICKET, TIME_BOUND_TICKET, , , NOT_APPLICABLE 0-999, NOT_APPLICABLE YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM:SS, isoldvoucher int Is Old Voucher 1 OLD, 0 - NEW status creationdate date Status of Voucher Voucher creation date soldby Transaction by ACTIVE, INACTIVE, PENDING, YYYY-MM-DD HH:MM:SS, ONLINE_SHOP, IN_STORE, ordernumber int Order Number 10 digit number invoicenumber int Invoice Number 10 digit number receiptnumber int Receipt Number 10 digit number paymentmethod Payment Method Characters product object Product object Product details object recipient object Recipient object Recipient details object Product Object:

4 name Product Name Max. 255 characters price double Product price ,99 taxrate double Tax rate externalsku External Sku is a unique identification code of a Product Max. 50 characters usually alphanumeric Recipient Object: name Recipient Name Max. 50 characters alphanumeric Recipient Address [email protected] address object Address Object Address details object Address Object: street Street postcode Postcode city City Name country Country Name Max. 100 characters Max. 10 characters Max. 20 characters Max. 20 characters

5 EXAMPLE: REQUEST: IJKL Or Request Sample: curl -v -X GET 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":" :00:00", "validtodate":" :00:00", "isoldvoucher":0, "status":"active", "creationdate":" :00:00", "soldby": "ONLINE_SHOP" "ordernumber": " " "invoicenumber": " " "receiptnumber": "NOT_APPLICABLE" "paymentmethod": "PAYPAL_STANDARD" "product":{

6 } } "name":"gift Voucher", "price":20, "taxrate":19, "externalsku":"gv123" }, "recipient":{ "name":"georg Dirk", " ": [email protected], "address":{ "street": Wittbräucker Str. 32, "postcode":44287, "city": Dortmund, "country": Germany } } XML format: <?xml version="1.0" encoding="utf-8"?> <xml> <voucher> <code>abcd-efgh-ijkl</code> <externalid>12345</externalid> <pin>1234</pin> <currencycode>eur</currencycode> <type>gift_voucher</type> <balance>20.00</balance> <numberofusesallowed>not_applicable</numberofusesallowed> <numberofusesremaining>not_applicable</numberofusesremaining> <validfromdate> :00:00</validFromDate> <validtodate> :00:00</validToDate> <isoldvoucher>0</isoldvoucher> <status>active</status> <creationdate> :00:00</creationDate> <soldby>online_shop</soldby> <ordernumber> </ordernumber> <invoicenumber> </invoicenumber> <receiptnumber>not_applicable</receiptnumber>

7 <paymentmethod>paypal_standard</paymentmethod> <product> <name>gift Voucher</name> <price>20</price> <taxrate>19</taxrate > <externalsku>gv123</externalsku> </product> <recipient> <name>georg Dirk</name> <address> <street>wittbräucker Str. 32</street> <postcode>44287</postcode> <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: Or {externalid}/sale Where {code} is voucher code and {externalid} is external ID of a voucher used in Consumer system. Request:

8 externalproductsku External Sku is a unique identification code of Product Max. 50 characters usually alphanumeric amount double Voucher sale value ,99 Date date Transaction Date YYYY-MM-DD HH:MM:SS Response: Property type Description Value details messagestatus Status of sale SUCCESS, FAILURE messagecode Unique code to identify message VOUCHER_SOLD_SUCCESSFULLY, VOUCHER_SALE_FAILED messagedescription Details of message Text Request Sample: curl -v 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= d Date= :00:00 3. Redeem a voucher: Redeem a Voucher by using voucher code or external ID with

9 Method: PUT Urls: {externalid}/redeem Where {code} is voucher code and {externalid} is external ID of a voucher used in Consumer system. Request: amount double Voucher sale value ,99 Date date Transaction Date YYYY-MM-DD HH:MM:SS Response: Property type Description Value details messagestatus Status of sale SUCCESS, FAILURE messagecode Unique code to identify message VOUCHER_REDEEMED_SUCCESSFULLY, VOUCHER_REDEMPTION_FAILED messagedescription Details of message Text Request Sample:

10 curl -v or ext-{externalid}/redeem \ -H "ACCEPT:application/json" \ -H "X-GURADO-CONSUMER-KEY: <Key-Token>" \ -H "X-GURADO-CONSUMER-SECRET: <Secret-Token>" \ -d amount= d Date= :00:59 4. List voucher s: Get List of voucher by using voucher code or external ID with Method: GET Urls : {externalid}/s 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. code Voucher Code externalid Voucher External ID Characters, Numbers and - are allowed Numbers pin int Secure Pin 4 digit number currencycode Currency code type Voucher Type Currency code like EUR, CHF GIFT_VOUCHER, TICKET, COUPON, SEASON_TICKET, MULTI_SCAN_TICKET, TIME_BOUND_TICKET,

11 balance numberofusesallowed double int numberofusesremaining int Balance of Voucher Total number of voucher usage allowed Total number of voucher usage remaining validfromdate date Valid From Date validtodate date Valid To Date , , NOT_APPLICABLE 0-999, NOT_APPLICABLE YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM:SS, isoldvoucher int Is Old Voucher 1 OLD, 0 - NEW status Status of Voucher creationdate date Transaction by ACTIVE, INACTIVE, PENDING, ONLINE_SHOP, IN_STORE, soldby 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 Product object Product details object product object Recipient object Recipient details object recipient object Transactions object List of voucher history s Product Object:

12 name Product Name Max. 255 characters price double Product price ,99 taxrate double Tax rate externalsku External Sku is a unique identification code of a Product Max. 50 characters usually alphanumeric Recipient Object: name Recipient Name Max. 50 characters alphanumeric Recipient Address [email protected] address object Address Object Address details object Address Object: street Street Max. 100 characters postcode Postcode Max. 10 characters city City Name Max. 20 characters country Country Name Max. 20 characters

13 Transaction Object: outlet Name of outlet that performed action Transaction action amount double Transaction amount date date Date of ordernumber receiptnumber int int externalreceiptnumber order number if voucher purchased online receipt number if voucher purchased in store External receipt number generated by consumer Max. 100 characters SALE, REDEEM, CORRECT ,99 YYYY-MM-DD HH:MM:SS, Max. 10 digit number Max. 10 digit number Max. 50 characters EXAMPLE: REQUEST IJKL/s or /s Request Sample: curl -v -X GET or ext-{externalid}/s \ -H "ACCEPT:application/json" \ -H "X-GURADO-CONSUMER-KEY: <Key-Token>" \ -H "X-GURADO-CONSUMER-SECRET: <Secret-Token>"

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":" :00:00", "validtodate":" :00:00", "isoldvoucher":0, "status":"active", "creationdate":" :00:00", "soldby": "ONLINE_SHOP" "ordernumber": " " "invoicenumber": " " "receiptnumber": "NOT_APPLICABLE" "paymentmethod": "PAYPAL_STANDARD" "product":{ "name":"gift Voucher", "price":20, "taxrate":19, "externalsku":"gv123" }, "recipient":{ "name":"georg Dirk", " ": [email protected], "address":{ "street": Wittbräucker Str. 32, "postcode":44287, "city": Dortmund, "country": Germany } }, "s":[

15 } } ] { }, { } "outlet":"gurado", "action":"sale", "amount":20, "date":" :00:00", "ordernumber":"not_applicable", "receiptnumber":" ", "externalreceiptnumber":"not_applicable" "outlet":"gurado", "action":"redeem", "amount":18, "date":" :00:00", "ordernumber":"not_applicable", "receiptnumber":" ", "externalreceiptnumber":"not_applicable" XML format: <?xml version="1.0" encoding="utf-8"?> <xml> <voucher> <code>abcd-efgh-ijkl</code> <externalid>12345</externalid> <pin>1234</pin> <currencycode>eur</currencycode> <type>gift_voucher</type> <balance>20.00</balance> <numberofusesallowed>not_applicable</numberofusesallowed> <numberofusesremaining>not_applicable</numberofusesremaining> <validfromdate> :00:00</validFromDate> <validtodate> :00:00</validToDate> <isoldvoucher>0</isoldvoucher>

16 <status>active</status> <creationdate> :00:00</creationDate> <soldby>online_shop</soldby> <ordernumber> </ordernumber> <invoicenumber> </invoicenumber> <receiptnumber>not_applicable</receiptnumber> <paymentmethod>paypal_standard</paymentmethod> <product> <name>gift Voucher</name> <price>20</price> <taxrate>20</taxrate > <externalsku>gv123</externalsku> </product> <recipient> <name>georg Dirk</name> <address> <street>wittbräucker Str. 32</street> <postcode>44287</postcode> <city>dortmund</city> <country>germany</country> </address> </recipient> <s> <> <outlet>gurado</outlet> <action>sale</action> <amount>20</amount> <date> :00:00</date> <ordernumber>not_applicable</ordernumber> <receiptnumber> </receiptnumber> <externalreceiptnumber>not_applicable</externalreceiptnumber> </> <> <outlet>gurado</outlet> <action>redeem</action> <amount>18</amount> <date> :00:00</date> <ordernumber>not_applicable</ordernumber>

17 <receiptnumber> </receiptnumber> <externalreceiptnumber>not_applicable</externalreceiptnumber> </> </s> </voucher> </xml> 5. Generate and sale a voucher: Generate and sale a Voucher Method: POST Urls: Request: externalproductsku External Sku is a unique identification code of Product Max. 50 characters usually alphanumeric amount double Voucher sale value ,99 Date date Transaction Date YYYY-MM-DD HH:MM:SS Response: Property type Description Value details messagestatus Status of generate SUCCESS, FAILURE messagecode Unique code to identify message AUTO_VOUCHER_GENERATION_NOT_ALLOWED, INVALID_AMOUNT, UNABLE_TO_GENERATE_NEW_VOUCHER, PRODUCT_NOT_FOUND, VOUCHER_SALE_FAILED

18 messagedescription Details of message Text Request Sample: curl -v \ -H "ACCEPT:application/json" \ -H "X-GURADO-CONSUMER-KEY: <Key-Token>" \ -H "X-GURADO-CONSUMER-SECRET: <Secret-Token>" \ -d externalproductsku=1245 -d amount= d Date= :00:00 6. List all vouchers: Get information of all vouchers with pagination Method: GET Urls: Request: fromdate todate page pagesize date date int int From Date (url encoded) To Date (url encoded) Current page number Number of vouchers per page YYYY-MM-DD HH:MM:SS Default all vouchers YYYY-MM-DD HH:MM:SS Default all vouchers Default 1 Default 20, Max 100 vouchers per page Response: Returns a list of Voucher objects in JSON or XML format.

19 code Voucher Code externalid Voucher External ID Characters, Numbers and - are allowed Numbers pin int Secure Pin 4 digit number currencycode Currency code Currency code like EUR, CHF type Voucher Type balance numberofusesallowed double int numberofusesremaining int Balance of Voucher Total number of voucher usage allowed Total number of voucher usage remaining validfromdate date Valid From Date validtodate date Valid To Date GIFT_VOUCHER, TICKET, COUPON, SEASON_TICKET, MULTI_SCAN_TICKET, TIME_BOUND_TICKET, , , NOT_APPLICABLE 0-999, NOT_APPLICABLE YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM:SS, isoldvoucher int Is Old Voucher 1 OLD, 0 - NEW status creationdate date Status of Voucher Voucher creation date soldby Transaction by ACTIVE, INACTIVE, PENDING, YYYY-MM-DD HH:MM:SS, ONLINE_SHOP, IN_STORE, ordernumber int Order Number 10 digit number invoicenumber int Invoice Number 10 digit number receiptnumber int Receipt Number 10 digit number paymentmethod Payment Method Characters product object Product object Product details object

20 recipient object Recipient object Recipient details object Product Object: name Product Name Max. 255 characters price double Product price ,99 taxrate double Tax Rate externalsku External Sku is a unique identification code of a Product Max. 50 characters usually alphanumeric Recipient Object: name Recipient Name Max. 50 characters alphanumeric Recipient Address [email protected] address object Address Object Address details object Address Object: street Street Max. 100 characters

21 postcode Postcode city City Name country Country Name Max. 10 characters Max. 20 characters Max. 20 characters Paging Object: total int Total Vouchers perpage int Vouchers per Page currentpage int Current Page lastpage int Last Page from int Vouchers From to int Vouchers To EXAMPLE: REQUEST: Request Sample: curl -v -X GET " >&pagesize=<page-size>" \ -H "ACCEPT:application/json" \ -H "X-GURADO-CONSUMER-KEY: <Key-Token>" \ -H "X-GURADO-CONSUMER-SECRET: <Secret-Token>"

22 7. Convert old to new voucher: Convert old to new voucher by using voucher code or external ID Method: PUT Urls: {externalid}/convert Where {code} is voucher code and {externalid} is external ID of a voucher used in Consumer system. Request: newvouchercode New voucher code Alphanumeric amount double Voucher correction value ,99 Date date Transaction Date YYYY-MM-DD HH:MM:SS Response: Property type Description Value details messagestatus Status of conversion SUCCESS, FAILURE messagecode Unique code to identify message VOUCHER_CONVERTED_SUCCESSFULLY, VOUCHER_CONVERSION_FAILED

23 messagedescription Details of message Text Request Sample: curl -v or ext-{externalid}/convert \ -H "ACCEPT:application/json" \ -H "X-GURADO-CONSUMER-KEY: <Key-Token>" \ -H "X-GURADO-CONSUMER-SECRET: <Secret-Token>" \ -d newvouchercode=xxxxx-xxxxx -d amount= d Date= :00:59