Environment Setup

Go2Joy API URL

Environment	URL	Rate Limiting
UAT	https://go2joy-partner-service-uat.go2joy.io/	~250 requests/ minute
Production	https://partnership.go2joy.vn	~500 requests/ minute

• Partner provides IP for whitelist

• APIs has Authorization by provide the signature via Authorization

• APIs provides 2 languages (Vietnamese, English) via Localization

• APIs needs default parameters: Client-ID, Timestamp

Type	Parameters	Description
Header	Authorization*	Signature of partners
Header	Localization	The language for title (en, vi). Default is en
Header	Timestamp*	The current timestamp when calling api. Expires in 5 minutes.
Header	Client-ID*	A secret key is distributed to partner.

How to configure authentication

1. Prerequisites

• You already have client id and client secret key.

• You already have a public app or web application.

2. Signature algorithm

Go2Joy verifies the identity of each API request, and the server will also verify whether the call parameters are valid. Therefore, each HTTP request must contain the signature information. The requests with invalid signature will be rejected.

This part explains how to generate an HMAC-SHA256 signature for an HTTP request. The request used to demonstrate signing is a POST to https://partnership.go2joy.vn/api/v1/hotel/updateHotelInfo. The raw request looks like this sample:

Copy

POST /api/v1/hotel/updateHotelInfo HTTP/1.1
Host: partnership.go2joy.vn
Content-Type: application/json
Client-ID: 8eabbb1b-feb7-4d12-b8fd-10046769a100
Timestamp: 1777924035
Authorization: 92db273a6b27703a72d828ff0ddf28fe26c2b0cc00c53ea7b354fb8460ce72e1

{"areaCode":"028","phone":"09012345678","name":"Bonita Tô Hiến Thành","description":"<p>Hãy đến với Bonita Tô Hiến Thành – Khách sạn chuẩn tình yêu 18+.</p>","enDescription":"<p>Come to Bonita To Hien Thanh - Love Hotel 18+.</p>","policy":null,"policyEn":null,"imageList":[{"sn":148606,"fullUrl":"https://staging-s3.go2joy.vn/350w/hotel/725/6130_1644393308_6203735c00286.jpg","firstDisplay":0,"flag":4}]}

3. Creating the signature base string

The three values collected must be joined to make a single string, from which the signature will be generated. This is called the signature base string.

Sort all request parameters according to the parameter name in ASCII table.

Example:

• Before sort:

Copy

{"areaCode":"028","phone":"09012345678","name":"Bonita Tô Hiến Thành","description":"<p>Hãy đến với Bonita Tô Hiến Thành – Khách sạn chuẩn tình yêu 18+.</p>","enDescription":"<p>Come to Bonita To Hien Thanh - Love Hotel 18+.</p>","policy":null,"policyEn":null,"imageList":[{"sn":148606,"fullUrl":"https://staging-s3.go2joy.vn/350w/hotel/725/6130_1644393308_6203735c00286.jpg","firstDisplay":0,"flag":4}]}

• After sort:

Copy

{"areaCode":"028","description":"<p>Hãy đến với Bonita Tô Hiến Thành – Khách sạn chuẩn tình yêu 18+.</p>","enDescription":"<p>Come to Bonita To Hien Thanh - Love Hotel 18+.</p>","imageList":[{"firstDisplay":0,"flag":4,"fullUrl":"https://staging-s3.go2joy.vn/350w/hotel/725/6130_1644393308_6203735c00286.jpg","sn":148606}],"name":"Bonita Tô Hiến Thành","phone":"09012345678","policy":null,"policyEn":null}

The signature base string is formed by concatenating Timestamp|URL|Body (Body must be encoded).

Copy

1777924035|https://partnership.go2joy.vn/api/v1/hotel/updateHotelInfo|{"areaCode":"028","description":"<p>Hãy đến với Bonita Tô Hiến Thành – Khách sạn chuẩn tình yêu 18+.</p>","enDescription":"<p>Come to Bonita To Hien Thanh - Love Hotel 18+.</p>","imageList":[{"firstDisplay":0,"flag":4,"fullUrl":"https://staging-s3.go2joy.vn/350w/hotel/725/6130_1644393308_6203735c00286.jpg","sn":148606}],"name":"Bonita Tô Hiến Thành","phone":"09012345678","policy":null,"policyEn":null}

There should be no space in the base string.

Note:

When using HMAC to sign the HTTP GET Request, you do not have a body. So your the signature base string is formed by concatenating Timestamp|URL (URL included query params. Query params must be sorted according to the parameter name in ASCII table too)

4. Client secret key

A secret key is distributed to partner when the registration is completed. Please keep the key as secret as your account password. Never disclose the key to anyone else.

5. Calculating the signature

Finally, the signature is calculated by passing the signature base string and client secret key to the HMAC-SHA256 hashing algorithm. The details of the algorithm are explained in depth here.

The output of the HMAC signing function is a binary string. This needs to be hex encoded to produce the signature string.

Copy

hash_hmac('sha256',<YOUR_SIGNATURE_BASE_STRING>,<YOUR_CLIENT_SECRET>)

Example:

Copy

hash_hmac('sha256','1777924035|https://partnership.go2joy.vn/api/v1/hotel/updateHotelInfo|{"areaCode":"028","description":"<p>Hãy đến với Bonita Tô Hiến Thành – Khách sạn chuẩn tình yêu 18+.</p>","enDescription":"<p>Come to Bonita To Hien Thanh - Love Hotel 18+.</p>","imageList":[{"firstDisplay":0,"flag":4,"fullUrl":"https://staging-s3.go2joy.vn/350w/hotel/725/6130_1644393308_6203735c00286.jpg","sn":148606}],"name":"Bonita Tô Hiến Thành","phone":"09012345678","policy":null,"policyEn":null}')

Sample code for PHP:

Copy

<?php
    const CLIENT_ID = '8eabbb1b-feb7-4d12-b8fd-10046769a100';
    const CLIENT_SECRET = 'f066739601bd38b6a6cc35a08ebf74bf0c2a77a5';
    
    $timestamp = time();
    $url = 'https://partnership.go2joy.vn/api/v1/hotel/updateHotelInfo';
    $body = [
        'hotelSn'       => 725,
        'areaCode'      => '028',
        'phone'         => '09012345678',
        'name'          => 'Bonita Tô Hiến Thành',
        'description'   => '<p>Hãy đến với Bonita Tô Hiến Thành – Khách sạn chuẩn tình yêu 18+.</p>',
        'enDescription' => '<p>Come to Bonita To Hien Thanh - Love Hotel 18+.</p>',
        'policy'        => null,
        'policyEn'      => null,
        'imageList' => [
            [
                "sn"           => 148606,
                "fullUrl"      => "https://staging-s3.go2joy.vn/350w/hotel/725/6130_1644393308_6203735c00286.jpg",
                "firstDisplay" => 0,
                "flag"         => 4,
            ],
        ],
    ];
    ksort($body);
    $bodyToJson = json_encode($body);
    $signature = hash_hmac('sha256', trim($timestamp . '|' . $url . '|' . $bodyToJson),CLIENT_SECRET);
    
    $headers['Authorization'] = $signature;
    $headers['Content-Type'] = 'application/json; charset=UTF-8';
    $headers['Localization'] = 'en';
    $headers['Client-ID'] = CLIENT_ID;
    $headers['Timestamp'] = $timestamp;
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    try {
        $result = curl_exec($ch);
        $curlErrNo = curl_errno($ch);
        $curlError = curl_error($ch);
        if ($result === false || $curlErrNo > 0 || $curlError) {
            echo $curlErrNo . PHP_EOL;
        } else {
            echo $result . PHP_EOL;
        }
        curl_close($ch);
    } catch (\Exception $e) {
        echo $e . PHP_EOL;
    }
?>