API docs by Redocly

Voucher Launcher (0.1.0-beta)

Download OpenAPI specification:Download

Developer Support: developer@botio.io License: Apache 2.0

Introduction

Voucher Launcher provides a voucher management and delivery service.

Signing API Requests

As part of request verification, every request MUST include a request timestamp in the x-botio-timestamp header and a signature of the request in the x-botio-signature header.

The timestamp in x-botio-timestamp is a Unix timestamp in milliseconds format containing the submitting time of the request.

The signature is a Base64-encoded digest of the request body and timestamp. This digest is generated using the HMAC-SHA256 algorithm, with the API secret serving as the secret key. The API secret is generated as part of API key and is unique to the key.

The following is an example of how to compute signature of the request body.

Go

// Create a new HMAC-SHA256 hash
mac := hmac.New(sha256.New, []byte(API_SECRET))
mac.Write([]byte(request.Body + timestamp))                
// Compute Base64 signature 
signature := base64.StdEncoding.EncodeToString(mac.Sum(nil))

Rate Limits

Voucher Launcher API applies the following rate limits for all API endpoints.

Package Rate Limits
Basic 1000 requests per month

In addition, the request rate MUST NOT exceed 100 requests per second.

Voucher

Voucher operations

Supported Messaging Platforms

Following is a list of messaging platform supported by Voucher Launcher.

Recipient Type Platform Descriptions
botiocrm line Line messaging API through Botio CRM. Botio CRM service MUST be enable for the store.

List vouchers

Return a paginated list of vouchers in from shop.

Authorizations:
(x-api-keyx-botio-signature)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "000000",
  • "results": {
    }
}

Create vouchers

Generate vouchers and deliver them to a recipient. If no recipient is specified, vouchers will be created but remain undelivered. The delivery method is specified by shop configuration and a combination ofrecipient_type and platform (refer to the request body description for details).

Additionally, if recipient_email is set and the email voucher option is enabled in the store settings, emails containing vouchers will be automatically sent to the recipient.

Authorizations:
(x-api-keyx-botio-signature)
Request Body schema: application/json
required
config_id
required
string

ID of voucher configuration used for this voucher.

count
integer [ 1 .. 1000 ]
Default: 1

Number of vouchers to be created by this request.

platform
string
Enum: "" "line"

Platform for delivering vouchers to target recipient. The available delivery platforms are determined by the specified recipient_type. If recipient_type is not specified, created vouchers will remain unsent.

recipient_type
string
Enum: "" "botiocrm"

Voucher delivery service. Voucher Launcher will use this service to send vouchers to target recipient via the channel specified by platform.

See. Supported Messaging Platforms for more detail

Note: Currently, only Botio CRM service is supported.

recipient_id
string

Recipient identification for using with the service specified in recipient_type

recipient_name
string

Name of the recipient.

recipient_email
string

Recipient's email. This email will be used to send vouchers to the recipient if email voucher is enable in shop setting.

recipient_phone
string

Recipient's phone number.

customer_note
string

Note to the recipient.

store_note
string

Note for the store. Recipient will not see this message.

Responses

Request samples

Content type
application/json
{
  • "config_id": "507f1f77bcf86cd799439011",
  • "count": 1,
  • "platform": "",
  • "recipient_type": "",
  • "recipient_id": "",
  • "recipient_name": "",
  • "recipient_email": "test@example.com",
  • "recipient_phone": "",
  • "customer_note": "",
  • "store_note": ""
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "000000",
  • "results": {
    }
}

Get voucher

Return an information of a voucher

Authorizations:
(x-api-keyx-botio-signature)
path Parameters
voucherId
required
string

Voucher ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "000000",
  • "results": {
    }
}

Redeem voucher

Redeem a voucher

Authorizations:
(x-api-keyx-botio-signature)
path Parameters
voucherId
required
string

Voucher ID

Request Body schema: application/json
redeem
required
boolean

If true, redeem the voucher

count
integer

Amount of redemptions.

code
string

Code for redeeming the voucher.

Responses

Request samples

Content type
application/json
{
  • "redeem": true,
  • "count": 0,
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "000000"
}