Gift Card API
Gift Card API
Embedded Files
Introduction
Introduction
This document describes the specifications needed to connect an external distributor interested in sharing Weekendesk Gift Cards.
Weekendesk Gift Cards have a monetary value that can be exchanged when purchasing any of the Weekendesk website offers by adding the Gift Card identifier and the activation code in the reservation page. This monetary value will be extracted from the final offer price. In case the offer price is lower than the Gift Card value, the user is able to use it again in other purchases until the balance of the Gift Card is 0.
In Weekendesk an offer will always be a package of room + activities. For the moment, there is no possibility for the client to change the room or the activity, as packages are unbreakable.
How to use the API
How to use the API
The workflow to be followed to use this API, is the following one:
Request of the creation of a Gift Card with a desired amount. In this request, the Gift Card can be customized with the name of the person who is buying (fromName), the name of the person who will receive it (toName) and a message. The background image must be selected if you are using our vouchers. This is just the card appearance, you will be able to use the Gift Card in any of the Weekendesk offers, no matter on the category. The different background options are:
ROMANTIC
ADVENTURE
WELLNESS
CULINARY
FAMILY
WEDEXPERIENCE
2. Once the Gift Card is created, you can retrieve the information of the current status of it. You will receive the information about the codes of the Gift Card, initial and current balance, activation and expiration dates and the status.
3. The API also allows you to retrieve the voucher url where you can download the document of the Gift Card. Voucher example.
Authentication
Authentication
The API supports Basic Authentication as defined in RFC2617. You will have to authenticate each one of your requests by adding the following header:
Authorization: Basic Base64Encode(USERNAME:PASSWORD)
Error response format
Error response format
{
"appName": "Giftcard API",
"date": "2022-12-23 10:11:42:169",
"traceId": "172037803a7d67c5",
"messages": [
"The giftcard requested by id does not exist."
],
"path": "uri=/giftcards/123"
}
If you receive an error that you want us to review, the traceId is needed to be able to track it.
For the errorCode field, we can have the following values:
BAD_REQUEST: When the json is not properly validated because of max/min, not null fields, etc.
SERVICE_UNAVAILABLE: When the service is not available.
INTERNAL_SERVER_ERROR: One service that we are consuming is returning an unknown error.
RESOURCE_NOT_FOUND: Not found response, like a booking not found by id.
POINT_OF_SALE_NOT_ALLOWED: the requested point of sale is not allowed.
GIFT_CARD_ALREADY_CANCELLED: the booking is already cancelled.
USED_GIFT_CARD: The selected Gift Card was already used and it can't be cancelled.
HTTP response status codes
HTTP response status codes
These are the common response codes for the API:
200 Success.
400 Bad request, detailed message with the error.
401 Request incorrectly authenticated.
404 Resource not found, detailed message with the error.
500 Internal server error.
503 Service not available.
Endpoints
Endpoints
We have two environments (staging and production) and dedicated credentials for each one. You must contact Weekendesk team to receive the access to any of the environments. You must use the following urls depending on the environment you are using:
Production: https://giftcard-api.weekendesk.com
POST /giftcards
POST /giftcards
Description
This route will allow you to create a Gift Card and receive the relevant information for the final user to use it in the Weekendesk website.
In the request body, you will have to select a combination of language + POS that matches your configuration. In case of empty values and if you just have one locale allowed, we will use it.
Request
Request
Request Parameters
Request Parameters
We will need body parameters. They are described in the section below.
Request body schema
Request body schema
CreateGiftcardRequest
Attributes
language [string] - Possible values: FR, ES, IT, NL. Example: FR
pointOfSale [string] - Possible values: FR, ES, IT, NL or BE. Example: FR
amount [number] - Balance that the user wants to add in the Gift Card (in cents). The maximum value by default is 5000€, but this can be changed on demand. Example: 50000
customization
backgroundImage [string] - Type of image that the user want to include in the Gift Card. Possible values [ROMANTIC, ADVENTURE, WELLNESS, FAMILY, CULINARY, WEDEXPERIENCE]. Example: ROMANTIC.
fromName [string] - This is an optional value. It is he name of the person that is buying the Gift Card. Example: Weekendesk
toName[string] - This is an optional value. It is the name of the person that will receive the Gift Card. Example: Distributor
message [string] - This is an optional value. It is the message that the person who is buying the Gift Card want to include in the card. Example: This is for you.
Request example
Request example
Request URL
https://giftcard-api.weekendesk.com/giftcards
CURL of the request
curl -X 'POST' \
'https://giftcard-api.weekendesk.com/giftcards' \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '{
"language": "fr",
"pointOfSale": "FR",
"amount": 50000,
"customization": {
"backgroundImage": "ROMANTIC",
"fromName": "Test",
"toName": "Test",
"message": "Test message"
}
}'
Response
Response
Response body schema
Response body schema
CreateGiftcardResponse
Attributes
id [string] - Unique identifier of the Gift Card. Example: 955d5ba6-1dd7-4484-9f12-a7bd4cecdba1.
activationCode [number] - 8 digits activation code of the Gift Card. Example: 19858819.
serialNumber [number] - 8 digits serial code of the Gift Card. Example: 10530321.
dates
activation [string] - Date when the Gift Card starts to be valid to use. It will be the purchase date by defaut. Example: 2022-12-16.
expiration [string] - Date until the Gift Card can be used. It will be one year after the purchase date by default. Example: 2023-12-16.
amounts
initial [number] - Initial amount of the Gift Card set by the user when the purchase is done. Example: 50000.
remaining [number] - Remaining amount of the Gift Card. In this case, it will be the same value as the inital one. Example: 30000.
status [string] - The current status of the Gift Card. Possible values: ACTIVE, EXPIRED, CANCELLED. In this case we will always return ACTIVE, as the activation will be directly done after the purchase. Example: ACTIVE
actions
retrieveURL [string] - The url that will allow you to retrieve the information for the created Gift Card. Example: https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1
cancelURL [string] - The url that will allow you to cancel a created Gift Card. Example: https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1/cancel
voucherURL [string] - The url that will return you the voucher for the Gift Card. Example: https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1/voucher-url
Response example
Response example
200 OK
{
"id": "955d5ba6-1dd7-4484-9f12-a7bd4cecdba1",
"activationCode": 19858819,
"serialNumber": 10530321,
"dates": {
"activation": "2022-12-16",
"expiration": "2023-12-16"
},
"amounts": {
"initial": 50000,
"remaining": 50000
},
"status": "ACTIVE",
"actions": {
"retrieveUrl": "https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1",
"cancelUrl": "https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1/cancel",
"voucherUrl": "https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1/voucher-url"
}
}
GET /giftcards/{giftcardId}
GET /giftcards/{giftcardId}
Description
This route provides you a way of extracting the details of a created Gift Card.
Our system internally checks if the gift card belongs to the requested distributor. In case of not belonging to you, you will receive a 404 - not found.
Request
Request
Request Parameters
Request Parameters
Path parameter:
giftcardId [string] * mandatory
Request example
Request example
Request URL
https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1
CURL of the request
curl -X 'GET' \ 'https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1' \
-H 'accept: */*'
Response
Response
Response schema
Response schema
GiftcardResponse
Attributes
id [string] - Unique identifier of the Gift Card. Example: 955d5ba6-1dd7-4484-9f12-a7bd4cecdba1.
activationCode [number] - 8 digits activation code of the Gift Card. Example: 19858819.
serialNumber [number] - 8 digits serial code of the Gift Card. Example: 10530321.
dates
activation [string] - Date when the Gift Card starts to be valid to use. It will be the purchase date by defaut. Example: 2022-12-16.
expiration [string] - Date until the Gift Card can be used. It will be one year after the purchase date by default. Example: 2023-12-16.
amounts
initial [number] - Initial amount of the Gift Card set by the user when the purchase is done. Example: 50000.
remaining [number] - Remaining amount of the Gift Card. Example: 30000.
status [string] - The current status of the Gift Card. Possible values: ACTIVE, EXPIRED, CANCELLED. Example: ACTIVE
Response example
Response example
200 OK
{
"id": "955d5ba6-1dd7-4484-9f12-a7bd4cecdba1",
"activationCode": 19858819,
"serialNumber": 10530321,
"dates": {
"activation": "2022-12-16",
"expiration": "2023-12-16"
},
"amounts": {
"initial": 50000,
"remaining": 50000
},
"status": "ACTIVE"
}
POST /giftcards/{giftcardId}/cancel
POST /giftcards/{giftcardId}/cancel
Description
This route will allow you to cancel a Gift Card that has been previously created.
Our system will check three conditions when trying to cancel a Gift Card:
The Gift Card exists.
The Gift Card hasn't been used (totally or partially).
The Gift Card hasn't been cancelled before.
If these 3 conditions are not met, we will return you an error explaining the reason why we are not accepting the cancellation.
Request
Request
Request Parameters
Request Parameters
Path parameter:
giftcardId [string] * mandatory
Request example
Request example
Request URL
https://giftcard-api.weekendesk.com/giftcards/c004a3b8-3201-420c-bded-0b23888c41b7/cancel
CURL of the request
curl -X 'POST' \
'https://giftcard-api.weekendesk.com/giftcards/c004a3b8-3201-420c-bded-0b23888c41b7/cancel' \
-H 'accept: */*' \
-d ''
Response
Response
Response body schema
Response body schema
CreateGiftcardResponse
Attributes
id [string] - Unique identifier of the Gift Card. Example: 955d5ba6-1dd7-4484-9f12-a7bd4cecdba1.
activationCode [number] - 8 digits activation code of the Gift Card. Example: 19858819.
serialNumber [number] - 8 digits serial code of the Gift Card. Example: 10530321.
dates
activation [string] - Date when the Gift Card starts to be valid to use. It will be the purchase date by defaut. Example: 2022-12-16.
expiration [string] - Date until the Gift Card can be used. It will be one year after the purchase date by default. Example: 2023-12-16.
amounts
initial [number] - Initial amount of the Gift Card set by the user when the purchase is done. Example: 50000.
remaining [number] - Remaining amount of the Gift Card. In this case, it will be the same value as the inital one. Example: 30000.
status [string] - The current status of the Gift Card. In this case we will always return CANCELLED. Example: CANCELLED.
Response example
Response example
200 OK
{
"id": "c004a3b8-3201-420c-bded-0b23888c41b7",
"activationCode": 58735676,
"serialNumber": 10530437,
"dates": {
"activation": "2023-01-20",
"expiration": "2024-01-20"
},
"amounts": {
"initial": 5000,
"remaining": 5000
},
"status": "CANCELLED"
}
GET /giftcards/{giftcardId}/voucher-url
GET /giftcards/{giftcardId}/voucher-url
Description
This endpoint allows you to get the voucher of a created Gift Card.
Our system internally checks if the Gift Card belongs to the requested distributor. In case of not belonging to you, you will receive a 404 - not found.
Request
Request
Request Parameters
Request Parameters
Path parameter:
giftcardId [string] * mandatory
Request example
Request example
Request URL
https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1/voucher-url
CURL of the request
curl -X 'GET' \ 'https://giftcard-api.weekendesk.com/giftcards/955d5ba6-1dd7-4484-9f12-a7bd4cecdba1/voucher-url' \
-H 'accept: */*'
Response
Response
Response schema
Response schema
GiftcardVoucherResponse
Attributes
voucherUrl [string] - Url to retrieve the voucher. Example: https://www.staging.weekendesk.fr/mvc/downloadvoucher.jsp?b=35494706&type=KlantCCAVFVoucher&ccavf=570425&checksum=a425c502509616f6364943847a3c4c0b.
Response example
Response example
200 OK
{
"voucherUrl": "https://www.staging.weekendesk.fr/mvc/downloadvoucher.jsp?b=35495063&type=KlantCCAVFVoucher&ccavf=570434&checksum=a02cc2dd7b3830c584c2d9cce1927237"
}
Page updated
Report abuse