Bắt đầu ngay

Giới thiệu

Để triển khai tích hợp với hệ thống Tingee, đối tác bắt buộc phải sử dụng Client ID và Secret Token và Sinh chữ ký nhằm xác thực và đảm bảo tính hợp lệ cho mỗi yêu cầu API.
Tài liệu này hướng dẫn chi tiết cách truy xuất các thông tin trên cho từng tài khoản đối tác.

---

Hướng dẫn lấy Client ID & Secret Token

• Bước 1. Truy cập vào hệ thống Tingee và đăng ký tài khoản của Đối tác.

Nếu đã có tài khoản, vui lòng đăng nhập tại màn hình đăng nhập.

• Bước 2. Tại giao diện màn hình chính, trỏ vào avatar của tài khoản, click vào mục Developers

• Bước 3. Tại giao diện trang Developers, Đối tác sẽ thấy được Client ID và Secret Token của mình

---

Sinh chữ ký Signature

Mỗi API request gửi đến Tingee cần kèm theo chữ ký số (signature) để đảm bảo tính toàn vẹn và xác thực danh tính đối tác.

Công thức sinh chữ ký

x-signature = HMAC_SHA512( x-request-timestamp + ":" + requestBody, secretToken )

Trong đó:

• x-request-timestamp — Thời điểm gửi request, format yyyyMMddHHmmssSSS (múi giờ UTC+7)
• requestBody — Chuỗi JSON của request body, đã qua JSON.stringify() (minified, không có khoảng trắng thừa)
• secretToken — Secret Token lấy từ trang Developers của tài khoản đối tác

Headers bắt buộc

Header	Bắt buộc	Ví dụ
x-client-id	✅	Mã định danh của đối tác do TINGEE cung cấp Xem cách lấy tại đây
x-request-timestamp	✅	20260101101122333
x-signature	✅	Chữ ký SHA-512
Content-Type	✅	application/json

Code mẫu

Node.js

const crypto = require('crypto');

function generateSignature(timestamp, requestBody, secretToken) {
  const message = `${timestamp}:${requestBody}`;
  return crypto
    .createHmac('sha512', secretToken)
    .update(message, 'utf8')
    .digest('hex');
}

// Ví dụ sử dụng
const timestamp = new Date()
  .toISOString()
  .replace(/[-:T.Z]/g, '')
  .slice(0, 17); // "yyyyMMddHHmmssSSS"

const body = JSON.stringify({ clientId: 'abc123', amount: 50000 });
const signature = generateSignature(timestamp, body, 'YOUR_SECRET_TOKEN');

// Gắn vào headers khi gọi API
const headers = {
  'Content-Type': 'application/json',
  'x-client-id': 'YOUR_CLIENT_ID',
  'x-request-timestamp': timestamp,
  'x-signature': signature,
};

C#

using System;
using System.Security.Cryptography;
using System.Text;

public class TingeeSignature
{
    public static string Generate(string timestamp, string requestBody, string secretToken)
    {
        var message = $"{timestamp}:{requestBody}";
        var keyBytes = Encoding.UTF8.GetBytes(secretToken);
        var messageBytes = Encoding.UTF8.GetBytes(message);

        using (var hmac = new HMACSHA512(keyBytes))
        {
            var hash = hmac.ComputeHash(messageBytes);
            return BitConverter.ToString(hash).Replace("-", "").ToLower();
        }
    }

    // Ví dụ sử dụng
    public static void Example()
    {
        var timestamp = DateTime.Now.ToString("yyyyMMddHHmmssfff");
        var body = "{\"clientId\":\"abc123\",\"amount\":50000}";
        var signature = Generate(timestamp, body, "YOUR_SECRET_TOKEN");

        // Gắn vào headers khi gọi API
        // request.Headers["x-client-id"] = "YOUR_CLIENT_ID";
        // request.Headers["x-request-timestamp"] = timestamp;
        // request.Headers["x-signature"] = signature;
    }
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class TingeeSignature {
    public static String generate(String timestamp, String requestBody, String secretToken)
            throws Exception {
        String message = timestamp + ":" + requestBody;

        Mac hmac = Mac.getInstance("HmacSHA512");
        SecretKeySpec keySpec = new SecretKeySpec(
            secretToken.getBytes(StandardCharsets.UTF_8), "HmacSHA512");
        hmac.init(keySpec);

        byte[] hash = hmac.doFinal(message.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder();
        for (byte b : hash) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    public static void main(String[] args) throws Exception {
        String timestamp = LocalDateTime.now()
            .format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"));
        String body = "{\"clientId\":\"abc123\",\"amount\":50000}";
        String signature = generate(timestamp, body, "YOUR_SECRET_TOKEN");

        System.out.println("x-signature: " + signature);
    }
}

PHP

function generateSignature(string $timestamp, string $requestBody, string $secretToken): string {
    $message = $timestamp . ':' . $requestBody;
    return hash_hmac('sha512', $message, $secretToken);
}

// Ví dụ sử dụng
$timestamp = date('YmdHisu'); // "yyyyMMddHHmmssSSS" — chú ý milliseconds
$body = json_encode(['clientId' => 'abc123', 'amount' => 50000]);
$signature = generateSignature($timestamp, $body, 'YOUR_SECRET_TOKEN');

$headers = [
    'Content-Type: application/json',
    'x-client-id: YOUR_CLIENT_ID',
    'x-request-timestamp: ' . $timestamp,
    'x-signature: ' . $signature,
];

Lưu ý quan trọng

• Không chia sẻ secretToken trong mã nguồn hoặc repository công khai.
• Timestamp không được vượt quá thời điểm hiện tại và không được cũ hơn 10 phút so với thời gian máy chủ Tingee (UTC+7).
• requestBody phải là kết quả của JSON.stringify(body) — chuỗi JSON minified, không thêm khoảng trắng hay format lại, để đảm bảo chữ ký khớp chính xác.

---

Cấu hình Webhook

• Tingee sẽ gửi các Requests HTTP (method POST) đến Webhook url của Đối tác khi mà có phát sinh giao dịch với các tài khoản của Đối tác liên kết trên Tingee.
  

• Đối tác cấu hình webhook url của mình tại mục Webhook trong giao diện trang Developers.

• Đối tác có thể cấu hình nhiều webhook url tùy theo nhu cầu

• Sẽ có 3 Loại áp dụng mà Đối tác có thể cấu hình với webhook url

  Loại áp dụng: Tất cả

  Tingee sẽ gửi webhook sang cho Đối tác khi có phát sinh giao dịch với mọi tài khoản của Đối tác

  Loại áp dụng: Số tài khoản ảo

  Tingee sẽ gửi webhook sang cho Đối tác khi có phát sinh giao dịch với các tài khoản mà Đối tác đã chọn

  Loại áp dụng: Cửa hàng

  Tingee sẽ gửi webhook sang cho Đối tác khi có phát sinh giao dịch với các cửa hàng mà Đối tác đã chọn

• Đối tác có thể chỉnh sửa Loại áp dụng, cập nhật URL hoặc xóa cấu hình Webhook sau khi đã lưu.

---

Nhật ký Webhook

• Đối tác có thể xem được lịch sử gửi Webhook (Trạng thái webhook, Số lần retry, Status code...) tại mục Nhật ký Webhook trên giao diện trang Developers