Mắt Bão Partner API SDK (TypeScript)

Thư viện TypeScript/Node.js để tích hợp nhanh với Mắt Bão Partner API. SDK tự động xử lý chữ ký HMAC-SHA256, thêm timestamp chống replay và gửi request qua HTTP client tích hợp của Node.js.

Đặc điểm

• Serialize payload bằng fast-json-stable-stringify.
• Hỗ trợ CommonJS (require) và ESM (import).
• Cung cấp High-level API (post) và Low-level API (buildRequest) nếu bạn muốn dùng thư viện HTTP riêng như Axios/fetch.

Yêu cầu

• Node.js >= 22.x

Cài đặt

npm i matbao-partner-sdk

Sử dụng

// CommonJS
const { MatBaoPartnerClient, PartnerApiError } = require("matbao-partner-sdk");

// Hoặc ES Modules
import { MatBaoPartnerClient, PartnerApiError } from "matbao-partner-sdk";

Khởi Tạo Client

Bạn cần các thông tin xác thực do hệ thống quản trị cung cấp:

const client = new MatBaoPartnerClient({
    baseUrl: "https://api.example.com", // Base URL của API
    partnerCode: "MATBAO", // Mã đối tác
    accessKey: "AK_X7K2M9P4Q8W1R6TZ", // Access Key
    secretKey: "hex_string...", // Secret Key
    timeout: 30000, // Tùy chọn, mặc định 30s
});

Gọi API

try {
    const result = await client.post("/api/partner/certificates", {
        customer_name: "Nguyễn Văn A",
        tax_code: "0123456789",
    });

    console.log(result);
} catch (err) {
    if (err instanceof PartnerApiError) {
        console.error("Mã lỗi:", err.code);
        console.error("HTTP Status:", err.httpStatus);
        console.error("Chi tiết:", err.raw);
    }
}

Low-Level API

Nếu bạn muốn tự dùng Axios/fetch:

const request = client.buildRequest(
    "POST",
    "/api/partner/certificates",
    payload,
);

// request = { url, method, headers, body, requestId }
const response = await axios({
    url: request.url,
    method: request.method,
    headers: request.headers,
    data: request.body,
});

API Hiện Có

• new MatBaoPartnerClient(config)
• client.post(path, payload?)
• client.buildRequest(method, path, payload?)

Ký Request

Canonical string:

access_key=<AK>&partner_code=<PC>&payload=<payload_json>&request_id=<UUID>

• payload_json dùng fast-json-stable-stringify.
• Key canonical được sort bằng Object.keys(params).sort().
• SDK tự thêm timestamp vào payload.

Body gửi đi:

{
    "payload": {
        "...": "...",
        "timestamp": 1721720663
    },
    "signature": "<hmac_sha256_hex>"
}

Cấu Trúc Request

SDK tự động tạo request với cấu trúc:

Headers:

X-Partner-Code: MATBAO
X-Access-Key: AK_X7K2M9P4Q8W1R6TZ
X-Request-Id: uuid-v4
Content-Type: application/json

Body:

{
    "payload": {
        "customer_name": "Nguyễn Văn A",
        "timestamp": 1721720663
    },
    "signature": "hmac_sha256_hex"
}

Mã Lỗi

| Mã lỗi | Ý nghĩa | | :-------------------------- | :--------------------------------------------- | | PARTNER_HEADERS_MISSING | Thiếu headers bắt buộc. | | PARTNER_INVALID | Partner hoặc Access Key không hợp lệ/inactive. | | PARTNER_TIMESTAMP_EXPIRED | Request đã hết hạn. | | PARTNER_REPLAY_REQUEST | Request ID đã được sử dụng. | | PARTNER_SIGNATURE_INVALID | Chữ ký HMAC-SHA256 không khớp. | | PARTNER_DATA_MISSING | Thiếu trường payload trong body. | | PARTNER_PAYLOAD_INVALID | Trường payload không phải JSON hợp lệ. | | SDK_CONFIG_INVALID | Cấu hình SDK không hợp lệ. | | SDK_NETWORK_ERROR | Lỗi kết nối mạng. | | SDK_TIMEOUT | Request vượt quá thời gian chờ. |

Kiểm Tra

npm test

Publish Package

npm login
npm run build
npm publish --access public