# HiTechCloud Developers — ngữ cảnh đầy đủ Nguồn: https://developers.hitechcloud.vn/ --- # Giới thiệu API Tools của HiTechCloud: một khoá API, hàng trăm endpoint tra cứu dữ liệu doanh nghiệp, thuế, tên miền và hạ tầng mạng Việt Nam, trả JSON thống nhất. API Tools của HiTechCloud là bộ API REST trả JSON, gom các nguồn dữ liệu công bố chính thức (Tổng cục Thuế, Cổng đăng ký doanh nghiệp, VNNIC, hệ thống đấu thầu quốc gia…) cùng bộ công cụ mạng và tiện ích lập trình vào một giao diện thống nhất. ## Bạn nhận được gì - Hàng trăm endpoint chia theo nhóm dịch vụ: doanh nghiệp & thuế, mạng & hạ tầng, tên miền & SSL, email & DNS, dữ liệu Việt Nam, logistics, tài chính, pháp lý… - Phản hồi JSON nhất quán; dữ liệu tra cứu kèm trường `nguon` và `cached_at` để biết dữ liệu lấy từ đâu và cũ hay mới. - Một khoá API cho cả tổ chức, giới hạn theo nhóm dịch vụ, IP và hạn mức tháng. - Tài liệu máy đọc được: OpenAPI, Postman, `llms.txt` và máy chủ MCP cho trợ lý AI. ## Máy chủ và định dạng | Mục | Giá trị | | --- | --- | | Base URL | `https://api-tools.hitechcloud.vn` | | Giao thức | HTTPS | | Xác thực | `X-API-Key` | | Định dạng | JSON (UTF-8) | ## Đọc tiếp - [Quickstart](/quickstart) — gọi endpoint đầu tiên trong 5 phút. - [Xác thực](/xac-thuc) — khoá API, phạm vi và hạn mức. - [API Reference](/reference) — toàn bộ endpoint, tham số và mã mẫu. - [Mã lỗi](/ma-loi) — cách xử lý từng mã lỗi. --- # Quickstart Bốn bước để gọi API Tools của HiTechCloud lần đầu: tạo tổ chức, lấy khoá API, gọi endpoint tra cứu và đọc phản hồi JSON, kèm mã mẫu cURL. 1. Đăng nhập [Cổng khách hàng](/) bằng HiTechCloud ID. Lần đầu bạn tạo một tổ chức — mọi khoá và hạn mức thuộc về tổ chức. 2. Vào mục **Khoá API** và tạo khoá. Khoá chỉ hiện đúng một lần: sao chép và cất vào biến môi trường ngay. 3. Gọi thử endpoint tra cứu doanh nghiệp (ví dụ bên dưới). 4. Đọc phản hồi, rồi xem [Mã lỗi](/ma-loi) để xử lý các trường hợp 401, 404, 429. ## Gọi endpoint đầu tiên ```bash export HITECH_API_KEY="" curl 'https://api-tools.hitechcloud.vn/api/tax/business/0316954486' \ -H "X-API-Key: $HITECH_API_KEY" \ -H 'Accept: application/json' ``` ## Phản hồi mẫu ```json { "ok": true, "mst": "0316954486", "ten": "CÔNG TY TNHH HITECH CLOUD", "trang_thai": "Đang hoạt động", "nguon": "gdt.gov.vn", "cached_at": "2026-10-31T09:00:00+07:00" } ``` > Chưa muốn viết code? Dùng thẳng mục **Công cụ** trong Cổng khách hàng — bạn tra cứu được ngay mà không cần nhập khoá. ## Bước tiếp theo - Duyệt [API Reference](/reference) và bấm **Thử ngay** trên từng endpoint. - Cài [SDK & CLI](/sdk) hoặc [kết nối MCP](/mcp) cho trợ lý AI. - Đặt [webhook](/webhooks) để nhận cảnh báo hạn mức. --- # Xác thực Mọi endpoint của API Tools HiTechCloud cần khoá API gửi qua header X-API-Key; tìm hiểu phạm vi, danh sách IP, giới hạn tần suất và cách xoay vòng khoá an toàn. Gửi khoá trong header `X-API-Key` ở mỗi yêu cầu. Thiếu hoặc sai khoá, server trả `401` kèm mã lỗi để bạn biết nguyên nhân. ```bash curl 'https://api-tools.hitechcloud.vn/api/countries' \ -H "X-API-Key: $HITECH_API_KEY" ``` > Không bao giờ đặt khoá trong URL, mã front-end hoặc kho mã nguồn. Gọi API từ server của bạn và giữ khoá trong biến môi trường hoặc kho bí mật. ## Phạm vi của một khoá - **Nhóm dịch vụ** — mỗi khoá chỉ gọi được các nhóm bạn bật (ví dụ chỉ “Doanh nghiệp & Thuế”). - **Endpoint hạn chế** — một số endpoint cần xin quyền riêng trong Cổng khách hàng. - **Danh sách IP** — tuỳ chọn, chỉ cho phép lời gọi từ các IP bạn khai. - **Hết hạn / thu hồi** — khoá hết hạn hoặc bị thu hồi sẽ bị từ chối ngay. - **Tốc độ & hạn mức** — số lượt gọi mỗi phút của khoá và hạn mức tháng của tổ chức. ## Xoay vòng khoá 1. Tạo khoá mới trong Cổng khách hàng. 2. Cập nhật ứng dụng sang khoá mới và triển khai. 3. Thu hồi khoá cũ — nhật ký gọi API cho biết khoá cũ còn được dùng ở đâu. Các lỗi xác thực và cách xử lý nằm ở trang [Mã lỗi](/ma-loi). --- # Token API cá nhân Token API cá nhân cho HiTechCloud User API (HostBill) quản lý dịch vụ, hoá đơn và tên miền, khác với khoá X-API-Key của API Tools; giữ bí mật như mật khẩu. HiTechCloud có hai bộ API độc lập: | Bộ API | Dùng để | Xác thực | | --- | --- | --- | | Tools API | Tra cứu dữ liệu, công cụ mạng | `X-API-Key` (khoá của tổ chức) | | User API (HostBill) | Quản lý dịch vụ, hoá đơn, tên miền của tài khoản my.hitechcloud.vn | Token đăng nhập của chính bạn | Token API cá nhân thuộc về một người dùng, không thuộc tổ chức. Hãy xem như mật khẩu: không chia sẻ, không đưa vào mã nguồn, thu hồi nếu nghi bị lộ. Mô tả đầy đủ các endpoint của User API, môi trường thử nghiệm và mã mẫu nằm ở mục [User API (HostBill)](/user-api). > Mã mẫu của User API chạy được trên môi trường thử nghiệm (OTE) — xem trang [Môi trường thử nghiệm](/sandbox). --- # Môi trường thử nghiệm Thử API của HiTechCloud mà không chạm dữ liệu thật: môi trường OTE cho User API và khoá giới hạn thấp cho API Tools để kiểm thử an toàn. ## User API: môi trường OTE User API có môi trường thử nghiệm OTE chạy độc lập, có sẵn tài khoản và dữ liệu mẫu. Gọi thoải mái, không ảnh hưởng hệ thống thật. | Môi trường | Host | Ghi chú | | --- | --- | --- | | Chính thức | `api.hitechcloud.vn` | Dữ liệu thật — thao tác có hiệu lực ngay | | Thử nghiệm (OTE) | `ote.hitechcloud.vn` | Dữ liệu mô phỏng; token đăng nhập hết hạn sau một ngày | ## Tools API: dùng thử có kiểm soát Các endpoint tra cứu là dữ liệu công khai nên không có bản mô phỏng riêng. Hãy tạo một khoá riêng cho môi trường phát triển, giới hạn nhóm dịch vụ và đặt hạn mức thấp, rồi dùng nút **Thử ngay** trong [API Tools](/api-tools). > Khoá bạn dán vào ô “Thử ngay” chỉ nằm trong bộ nhớ trình duyệt của trang đang mở, gửi tới máy chủ qua HTTPS để gọi hộ rồi bỏ — không lưu, không ghi log, không đưa lên URL. --- # Cổng thanh toán — HiTechCloud Pay Cổng thanh toán HiTechCloud Pay: nhận tiền qua QR VietQR/NAPAS 247, thẻ quốc tế Visa/Mastercard, Apple Pay và ví điện tử trên một luồng checkout và IPN thống nhất. HiTechCloud Pay là nền tảng cổng thanh toán thông minh được tối ưu hóa cho doanh nghiệp Việt Nam. Với HiTechCloud Pay, bạn có thể triển khai giải pháp nhận tiền chuyển khoản tự động qua mã QR ngân hàng chỉ trong 5 phút, tích hợp thẻ quốc tế, đồng thời theo dõi và đối soát tự động qua hệ thống Webhook và Instant Payment Notification (IPN). - **Bắt đầu nhanh (5 phút)** — Tích hợp QR chuyển khoản tự động chỉ trong vài phút. (/cong-thanh-toan/bat-dau) - **Luồng thanh toán** — Checkout → trả tiền → đối soát tự động, end-to-end. (/cong-thanh-toan/luong-thanh-toan) - **Môi trường Sandbox** — Thử nghiệm toàn bộ luồng trước khi lên Production. (/cong-thanh-toan/sandbox) - **API & Xác thực** — Tạo form checkout, kiểm tra đơn hàng và xử lý IPN. (/cong-thanh-toan/API/tong-quan) ## Các phương thức thanh toán hỗ trợ - **Quét mã QR chuyển khoản ngân hàng (VietQR)**: Tạo mã QR động kèm thông tin số tiền và nội dung chuyển khoản cho từng đơn hàng. Khách hàng quét mã qua ứng dụng ngân hàng bất kỳ, hệ thống ghi nhận thanh toán thành công trong 1-3 giây. - **Quét mã QR NAPAS chuyển khoản ngân hàng**: Kết nối cổng chuẩn thanh toán liên ngân hàng NAPAS 247 với độ tin cậy và hạn mức tối đa. - **Thanh toán bằng thẻ (Visa / Mastercard / JCB)**: Xử lý thẻ thanh toán quốc tế và nội địa qua chuẩn bảo mật PCI-DSS và 3D-Secure 2.0. - **Ví điện tử & phương thức số**: Tích hợp các ví điện tử hàng đầu tại Việt Nam. ## Môi trường và Base URLs | Môi trường | Host Checkout (Gửi form) | Host REST API (Tra cứu đơn hàng) | | --- | --- | --- | | Production (Chính thức) | `https://pay-gateways.hitechcloud.vn/v1/checkout/init` | `https://pgapi.hitechcloud.vn` | | Sandbox (Thử nghiệm) | `https://pay-sandbox.hitechcloud.vn/v1/checkout/init` | `https://pgapi-sandbox.hitechcloud.vn` | ## Xác thực và Chữ ký bảo mật Mọi giao dịch thanh toán khởi tạo từ website của bạn đều được bảo vệ bằng chữ ký HMAC-SHA256 với `SECRET_KEY` được cấp riêng cho từng Merchant. Khi khách hàng hoàn tất chuyển khoản, HiTechCloud Pay sẽ gửi tín hiệu IPN (Instant Payment Notification) có chữ ký số xác thực đến máy chủ của bạn để kích hoạt đơn hàng tức thì. > Môi trường Sandbox và Production sử dụng hai bộ Merchant ID và Secret Key hoàn toàn riêng biệt. Bạn có thể kiểm thử toàn bộ quy trình thanh toán trên Sandbox mà không lo phát sinh giao dịch thật. ## Danh mục hướng dẫn - [Luồng thanh toán](/cong-thanh-toan/luong-thanh-toan) — Chi tiết chu trình giao dịch thanh toán một lần và định kỳ. - [Bắt đầu nhanh](/cong-thanh-toan/bat-dau) — Hướng dẫn 5 bước tích hợp từ đăng ký tới go-live. - [Môi trường Sandbox](/cong-thanh-toan/sandbox) — Thiết lập môi trường thử nghiệm và lấy key test. - [API Tổng quan](/cong-thanh-toan/API/tong-quan) — Đặc tả API, xác thực Basic Auth, mã lỗi và phân trang. - [API Tạo form thanh toán](/cong-thanh-toan/API/don-hang/form-thanh-toan) — Tham số khởi tạo checkout và tính chữ ký HMAC. - [API Kiểm tra đơn hàng](/cong-thanh-toan/API/don-hang/kiem-tra-don-hang) — Tra cứu trạng thái đơn hàng và giao dịch. - [Cấu hình & Xử lý IPN](/cong-thanh-toan/API/ipn) — Tiếp nhận và xử lý webhook thông báo thanh toán thành công. --- # Luồng thanh toán Cổng Thanh Toán HiTechCloud Pay Luồng thanh toán của Cổng thanh toán HiTechCloud Pay: so sánh thanh toán một lần (one-time) và định kỳ (recurring), từ tạo đơn đến nhận kết quả IPN. Cổng thanh toán HiTechCloud Pay hỗ trợ mô hình thanh toán chuyển khoản và thẻ thông qua luồng chuyển hướng (Redirect Flow) an toàn, đảm bảo thông tin bảo mật của khách hàng không lưu trữ trên máy chủ merchant. ## Luồng thanh toán một lần (One-time Payment) 1. **Khách hàng chọn sản phẩm**: Thêm hàng vào giỏ và nhấn Thanh toán trên website/ứng dụng của bạn. 2. **Website tạo đơn hàng**: Khởi tạo bản ghi đơn hàng trong cơ sở dữ liệu nội bộ với trạng thái `PENDING`. 3. **Tạo form checkout**: Chuẩn bị các trường dữ liệu đơn hàng và tính chữ ký số `signature` bằng thuật toán HMAC-SHA256 với `SECRET_KEY`. 4. **Gửi request đến HiTechCloud Pay**: POST form đến endpoint `https://pay-gateways.hitechcloud.vn/v1/checkout/init` (hoặc `pay-sandbox.hitechcloud.vn` trên môi trường test). 5. **HiTechCloud Pay xác thực signature**: Cổng kiểm tra tính toàn vẹn của chữ ký, kiểm tra `merchant_id` và tạo phiên thanh toán. 6. **Chuyển hướng khách hàng**: Hiển thị trang thanh toán bảo mật của HiTechCloud Pay với mã QR VietQR động hoặc form nhập thẻ. 7. **Khách hàng thực hiện thanh toán**: Khách hàng mở ứng dụng ngân hàng quét mã QR hoặc nhập thông tin thẻ để xác thực OTP (3D Secure). 8. **Xử lý giao dịch**: HiTechCloud Pay giao tiếp trực tiếp với hệ thống ngân hàng / tổ chức thẻ. 9. **Gửi thông báo IPN (Server-to-Server)**: Ngay khi nhận được tiền, HiTechCloud Pay gọi endpoint IPN đã cấu hình trên server của bạn kèm thông tin chi tiết giao dịch. 10. **Chuyển hướng khách hàng về Website**: Sau khi hoàn tất thanh toán, khách hàng được tự động chuyển hướng về `success_url` (nếu thành công), `error_url` (nếu lỗi) hoặc `cancel_url` (nếu huỷ). 11. **Hiển thị kết quả**: Website của bạn hiển thị trang cảm ơn và cập nhật trạng thái đơn hàng cho khách. ## Sơ đồ luồng giao tiếp ```mermaid sequenceDiagram autonumber actor Khach as Khách hàng participant Web as Website của bạn participant Gate as HiTechCloud Pay Gateway participant Bank as Ngân hàng / Napas Khach->>Web: Chọn mua sản phẩm & bấm Thanh toán Web->>Web: Tạo đơn hàng & tính signature HMAC-SHA256 Web->>Gate: POST /v1/checkout/init (form data + signature) Gate->>Gate: Xác thực signature & khởi tạo phiên Gate-->>Khach: Hiển thị trang thanh toán (Mã QR / Form thẻ) Khach->>Bank: Quét mã QR chuyển tiền qua App Ngân hàng Bank-->>Gate: Báo có giao dịch thành công tức thời Gate->>Web: Gửi tín hiệu IPN (POST JSON dữ liệu giao dịch) Web-->>Gate: Trả lời HTTP 200 {"success": true} Gate-->>Khach: Tự động chuyển hướng về success_url Web-->>Khach: Hiển thị trang Đặt hàng thành công ``` ## Thanh toán định kỳ (Recurring Payment) > Tính năng thanh toán định kỳ theo chu kỳ (Subscription / Recurring) đang được mở theo dạng đăng ký riêng cho doanh nghiệp đáp ứng tiêu chuẩn xử lý token hóa thẻ. Vui lòng liên hệ bộ phận hỗ trợ HiTechCloud Pay để được kích hoạt. --- # Bắt đầu nhanh với Cổng thanh toán HiTechCloud Pay Bắt đầu với Cổng thanh toán HiTechCloud Pay trong năm bước: đăng ký tài khoản, tạo form checkout, cấu hình IPN, kiểm thử trên sandbox và go-live. Hướng dẫn từng bước tích hợp cổng thanh toán HiTechCloud Pay vào ứng dụng của bạn trong 5 phút với phương thức quét mã QR chuyển khoản ngân hàng tự động. ## Bước 1: Đăng ký tài khoản và Lấy API Key 1. Truy cập `https://my.hitechcloud.vn` và đăng ký hoặc đăng nhập tài khoản. 2. Vào mục **Cổng thanh toán** → chọn **Phương thức thanh toán**. 3. Chọn **Bắt đầu ngay** với môi trường **Sandbox** để nhận thông tin tích hợp thử nghiệm. 4. Hệ thống sẽ cấp cho bạn: `MERCHANT ID` (ví dụ: `HTC_MCH_123456`) và `SECRET KEY` (chuỗi bí mật dùng để ký HMAC). Lưu lại hai giá trị này. ## Bước 2: Tạo form thanh toán trên website của bạn Bạn có thể sử dụng SDK chính thức hoặc tạo form POST HTML trực tiếp với chữ ký số HMAC-SHA256. ```php $merchant_id, 'operation' => 'PURCHASE', 'order_invoice_number' => 'INV-' . time(), 'order_amount' => 100000, 'order_currency' => 'VND', 'order_description' => 'Thanh toan don hang test', 'success_url' => 'https://example.com/payment/success', 'error_url' => 'https://example.com/payment/error', 'cancel_url' => 'https://example.com/payment/cancel', ]; // Tạo chữ ký HMAC-SHA256 từ các tham số sắp xếp theo key ksort($data); $sign_string = urldecode(http_build_query($data)); $signature = hash_hmac('sha256', $sign_string, $secret_key); $data['signature'] = $signature; ?>
$val): ?>
``` ```javascript const crypto = require('crypto'); function createCheckoutPayload(order) { const merchantId = process.env.HITECHCLOUD_PAY_MERCHANT_ID; const secretKey = process.env.HITECHCLOUD_PAY_SECRET_KEY; const isProd = process.env.NODE_ENV === 'production'; const checkoutUrl = isProd ? 'https://pay-gateways.hitechcloud.vn/v1/checkout/init' : 'https://pay-sandbox.hitechcloud.vn/v1/checkout/init'; const params = { merchant_id: merchantId, operation: 'PURCHASE', order_invoice_number: order.invoiceNumber, order_amount: order.amount, order_currency: 'VND', order_description: order.description, success_url: 'https://example.com/payment/success', error_url: 'https://example.com/payment/error', cancel_url: 'https://example.com/payment/cancel', }; // Sắp xếp key theo alphabet và tạo chuỗi ký const sortedKeys = Object.keys(params).sort(); const signString = sortedKeys.map(k => `${k}=` + params[k]).join('&'); const signature = crypto.createHmac('sha256', secretKey).update(signString).digest('hex'); return { checkoutUrl, fields: { ...params, signature } }; } ``` ```python import hmac import hashlib import urllib.parse import time def generate_checkout_payload(order_invoice: str, amount: int, description: str): merchant_id = "YOUR_MERCHANT_ID" secret_key = "YOUR_SECRET_KEY" checkout_url = "https://pay-sandbox.hitechcloud.vn/v1/checkout/init" params = { "merchant_id": merchant_id, "operation": "PURCHASE", "order_invoice_number": order_invoice, "order_amount": str(amount), "order_currency": "VND", "order_description": description, "success_url": "https://example.com/payment/success", "error_url": "https://example.com/payment/error", "cancel_url": "https://example.com/payment/cancel", } # Sắp xếp theo key A-Z sorted_pairs = sorted(params.items(), key=lambda x: x[0]) sign_string = "&".join(f"{k}={v}" for k, v in sorted_pairs) signature = hmac.new( secret_key.encode('utf-8'), sign_string.encode('utf-8'), hashlib.sha256 ).hexdigest() params["signature"] = signature return {"checkout_url": checkout_url, "params": params} ``` ```go package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "fmt" "sort" "strings" ) func GenerateCheckoutSignature(params map[string]string, secretKey string) string { keys := make([]string, 0, len(params)) for k := range params { if k != "signature" { keys = append(keys, k) } } sort.Strings(keys) var parts []string for _, k := range keys { parts = append(parts, fmt.Sprintf("%s=%s", k, params[k])) } signString := strings.Join(parts, "&") mac := hmac.New(sha256.New, []byte(secretKey)) mac.Write([]byte(signString)) return hex.EncodeToString(mac.Sum(nil)) } ``` ```csharp using System; using System.Collections.Generic; using System.Linq; using System.Security.Cryptography; using System.Text; public class HiTechCloudCheckout { public static string CreateSignature(Dictionary parameters, string secretKey) { var sortedParams = parameters .Where(p => p.Key != "signature") .OrderBy(p => p.Key, StringComparer.Ordinal) .Select(p => $"{p.Key}={p.Value}"); string rawData = string.Join("&", sortedParams); using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey))) { byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawData)); return BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant(); } } } ``` ## Bước 3: Cấu hình và Xử lý IPN (Instant Payment Notification) IPN là cơ chế thông báo Server-to-Server. Khi khách chuyển khoản thành công, máy chủ HiTechCloud Pay sẽ gửi một HTTP POST request chứa dữ liệu giao dịch đến URL IPN của bạn. ```json { "timestamp": 1759134682, "notification_type": "ORDER_PAID", "order": { "id": "e2c195be-c721-47eb-b323-99ab24e52d85", "order_id": "HTC-68DA43D73C1A5", "order_status": "CAPTURED", "order_currency": "VND", "order_amount": "100000.00", "order_invoice_number": "INV-1759134677", "order_description": "Thanh toan don hang test" }, "transaction": { "id": "384c66dd-41e6-4316-a544-b4141682595c", "payment_method": "BANK_TRANSFER", "transaction_id": "68da43da2d9de", "transaction_type": "PAYMENT", "transaction_date": "2025-09-29 15:31:22", "transaction_status": "APPROVED", "transaction_amount": "100000", "transaction_currency": "VND" } } ``` ```php false, 'message' => 'Invalid payload']); exit; } if ($data['notification_type'] === 'ORDER_PAID') { $invoice_number = $data['order']['order_invoice_number']; $amount = $data['transaction']['transaction_amount']; $trans_id = $data['transaction']['transaction_id']; // 1. Kiểm tra đơn hàng trong CSDL nội bộ // 2. Chống xử lý trùng lặp bằng transaction_id // 3. Đánh dấu đơn hàng ĐÃ THANH TOÁN (Paid) và cấp phát dịch vụ } // Bắt buộc phản hồi HTTP 200 kèm {"success": true} http_response_code(200); header('Content-Type: application/json'); echo json_encode(['success' => true]); ``` ## Bước 4: Kiểm thử trên Sandbox Tạo đơn hàng trên form của bạn. Trình duyệt chuyển hướng đến trang thanh toán giả lập của HiTechCloud Pay. Tại đây bạn bấm nút 'Mô phỏng thanh toán thành công' để hệ thống tự động bắn IPN và chuyển hướng về `success_url` của bạn. ## Bước 5: Chuyển sang Production (Go-Live) 1. Đăng nhập `https://my.hitechcloud.vn` → Cổng thanh toán → Chọn **Chuyển sang Production**. 2. Liên kết tài khoản ngân hàng nhận tiền thật của doanh nghiệp hoặc cá nhân. 3. Lấy `MERCHANT ID` và `SECRET KEY` của Production. 4. Thay đổi endpoint checkout thành `https://pay-gateways.hitechcloud.vn/v1/checkout/init`. 5. Thay đổi endpoint REST API tra cứu thành `https://pgapi.hitechcloud.vn`. 6. Cập nhật URL IPN và các Callback URL sang máy chủ Production của bạn. --- # Môi trường Sandbox Cổng thanh toán HiTechCloud Pay Môi trường thử nghiệm (sandbox) của Cổng thanh toán HiTechCloud Pay: mô phỏng đầy đủ luồng QR VietQR và thẻ, cách ly hoàn toàn và không phát sinh tiền thật. Sandbox là môi trường thử nghiệm độc lập của HiTechCloud Pay, cho phép lập trình viên kiểm tra toàn bộ luồng thanh toán, kiểm thử IPN callback, xử lý ngoại lệ và tự động hóa quy trình mà không cần tiền thật hay tài khoản ngân hàng thương mại. ## Thông số kết nối Sandbox | Mục | Giá trị Sandbox | Mô tả | | --- | --- | --- | | Host Checkout (Form) | `https://pay-sandbox.hitechcloud.vn/v1/checkout/init` | Endpoint gửi form POST đơn hàng từ trình duyệt | | Host REST API | `https://pgapi-sandbox.hitechcloud.vn` | Host gọi API tra cứu đơn hàng, giao dịch | | Xác thực REST API | `Authorization: Basic base64(merchant_id:secret_key)` | Dùng Merchant ID & Secret Key của Sandbox | | Portal cấu hình | `https://my.hitechcloud.vn` | Bật chế độ Sandbox/Test mode trên bảng điều khiển | ## Tài khoản Ngân hàng mô phỏng (Test Bank Accounts) | Ngân hàng | Số tài khoản test | Tên chủ tài khoản | Chi nhánh | | --- | --- | --- | --- | | Vietcombank (VCB) | `9988776655` | CONG TY TNHH HITECHCLOUD TEST | Hồ Chí Minh | | MBBank (Quân Đội) | `090912345678` | CONG TY TNHH HITECHCLOUD TEST | Hà Nội | | Techcombank (TCB) | `190367890123` | CONG TY TNHH HITECHCLOUD TEST | Đà Nẵng | | ACB (Á Châu) | `246813579` | CONG TY TNHH HITECHCLOUD TEST | Sài Gòn | ## Thẻ quốc tế thử nghiệm (Test Cards & 3D Secure) | Loại thẻ | Số thẻ thử nghiệm | Hạn sử dụng | CVV | Kịch bản kiểm thử | | --- | --- | --- | --- | --- | | Visa Success | `4000 0000 0000 0001` | 12/30 | 123 | Thanh toán thành công ngay lập tức (OTP: 123456) | | Visa Insufficient Funds | `4000 0000 0000 0002` | 12/30 | 123 | Lỗi không đủ số dư trong thẻ (HTTP 422) | | Mastercard Blocked | `5100 0000 0000 0003` | 12/30 | 123 | Lỗi thẻ bị ngân hàng phát hành khóa (Blocked) | | JCB 3DS Failed | `3528 0000 0000 0004` | 12/30 | 123 | Thất bại xác thực OTP 3D-Secure | ## Mô phỏng thanh toán qua cURL (Trigger IPN) Ngoài việc bấm nút trên trang thanh toán giả lập, bạn có thể gọi API Sandbox để chủ động kích hoạt gửi IPN cho một hóa đơn: ```bash curl -X POST "https://pgapi-sandbox.hitechcloud.vn/v1/sandbox/simulate-payment" \ -H "Authorization: Basic $(echo -n 'YOUR_SANDBOX_MERCHANT_ID:YOUR_SANDBOX_SECRET_KEY' | base64)" \ -H "Content-Type: application/json" \ -d '{ "order_invoice_number": "INV-1759134677", "status": "APPROVED", "amount": 100000 }' ``` --- # Tổng quan API Cổng Thanh Toán HiTechCloud Pay Đặc tả REST API Cổng thanh toán HiTechCloud Pay: xác thực, ký chữ ký, mã phản hồi HTTP, phân trang và chuẩn dữ liệu dùng chung cho mọi endpoint. Ngoài việc khởi tạo thanh toán qua form Checkout, HiTechCloud Pay cung cấp bộ REST API chuẩn cho phép máy chủ của bạn tra cứu trạng thái đơn hàng, đối soát các giao dịch đã thu và kiểm tra lịch sử thanh toán. ## Base URLs | Môi trường | Base URL | | --- | --- | | Production | `https://pgapi.hitechcloud.vn` | | Sandbox | `https://pgapi-sandbox.hitechcloud.vn` | ## Phương thức xác thực Mọi cuộc gọi đến REST API Cổng thanh toán đều sử dụng HTTP Basic Authentication với username là `merchant_id` và password là `secret_key`. ```http Authorization: Basic base64(YOUR_MERCHANT_ID:YOUR_SECRET_KEY) Content-Type: application/json Accept: application/json ``` ## Bảng mã lỗi chi tiết (API Error Codes) | Mã HTTP | Error Code | Ý nghĩa & Nguyên nhân | Cách xử lý | | --- | --- | --- | --- | | `400` | `INVALID_SIGNATURE` | Chữ ký HMAC-SHA256 không hợp lệ hoặc sai secret key | Kiểm tra thứ tự sắp xếp tham số và secret key | | `400` | `MISSING_REQUIRED_FIELD` | Thiếu trường dữ liệu bắt buộc | Bổ sung đầy đủ merchant_id, order_invoice_number... | | `401` | `UNAUTHORIZED` | Sai Merchant ID hoặc Secret Key | Xác thực lại cặp khóa trên my.hitechcloud.vn | | `403` | `IP_NOT_ALLOWED` | Địa chỉ IP gọi API không nằm trong Whitelist | Đăng ký IP máy chủ tại mục Bảo mật API | | `404` | `ORDER_NOT_FOUND` | Không tìm thấy đơn hàng với mã hóa đơn yêu cầu | Kiểm tra lại order_invoice_number | | `409` | `ORDER_ALREADY_PAID` | Đơn hàng này đã được thanh toán trước đó | Không được phép khởi tạo thanh toán lại cho đơn đã thanh toán | | `410` | `ORDER_EXPIRED` | Phiên thanh toán đã hết hạn | Khởi tạo phiên thanh toán mới cho khách | | `422` | `AMOUNT_BELOW_MINIMUM` | Số tiền thanh toán nhỏ hơn mức tối thiểu (1,000 VNĐ) | Cập nhật số tiền đơn hàng hợp lệ | | `429` | `RATE_LIMIT_EXCEEDED` | Vượt quá hạn mức 60 req/phút | Giảm tần suất polling, áp dụng Exponential Backoff | | `500` | `INTERNAL_SERVER_ERROR` | Lỗi máy chủ HiTechCloud Pay | Liên hệ bộ phận kỹ thuật để hỗ trợ | ## Cấu trúc phản hồi lỗi chuẩn (JSON) ```json { "status": "error", "code": "INVALID_SIGNATURE", "message": "Chữ ký HMAC-SHA256 không khớp với dữ liệu gửi lên.", "errors": { "signature": [ "Signature verification failed for merchant HTC_MCH_123456" ] }, "timestamp": 1759134700 } ``` ## Rate Limiting Headers | Header | Mô tả | | --- | --- | | `X-RateLimit-Limit` | Số lượng request tối đa được phép trong 1 phút (mặc định 60) | | `X-RateLimit-Remaining` | Số lượng request còn lại trong cửa sổ thời gian hiện tại | | `X-RateLimit-Reset` | Thời điểm (Unix timestamp) giới hạn được reset lại | --- # Webhooks — HiTechCloud Pay Webhook giao dịch thời gian thực của HiTechCloud Pay: nhận thông báo tiền vào, tiền ra từ tài khoản ngân hàng, ví điện tử và tài khoản ảo ngay về máy chủ của bạn. HiTechCloud Pay Webhooks là giải pháp thông báo biến động số dư ngân hàng theo thời gian thực dành cho doanh nghiệp. Mỗi khi tài khoản ngân hàng hoặc tài khoản ảo của bạn phát sinh giao dịch nhận tiền (hoặc chuyển tiền), HiTechCloud Pay sẽ ngay lập tức gửi một HTTP POST request chứa toàn bộ dữ liệu giao dịch chi tiết tới máy chủ của bạn. ## Lợi ích cốt lõi - **Tự động hóa 100%**: Xóa bỏ hoàn toàn thao tác kiểm tra sao kê ngân hàng thủ công, đối soát tự động theo mã đơn hàng. - **Độ trễ thấp (1-3s)**: Nhận thông báo gần như tức thì ngay khi tin nhắn ngân hàng hoặc biến động số dư phát sinh. - **Bảo mật đa tầng**: Hỗ trợ 4 phương thức xác thực mạnh mẽ gồm HMAC-SHA256, API Key, OAuth 2.0 Client Credentials và Whitelist IP. - **Cơ chế tự động gửi lại (Retry)**: Đảm bảo không bao giờ bỏ sót giao dịch ngay cả khi máy chủ của bạn bảo trì hoặc nghẽn mạng. ## Sơ đồ luồng gửi Webhook ```mermaid sequenceDiagram autonumber actor User as Khách hàng participant Bank as Ngân hàng (VCB, MB, TCB...) participant HTC as HiTechCloud Pay Engine participant Webhook as Server của bạn (Webhook Receiver) participant DB as CSDL của bạn User->>Bank: Quét mã QR chuyển khoản ngân hàng Bank-->>HTC: Báo có biến động số dư (SMS/API/OpenBanking) HTC->>HTC: Phân tích mã đơn, bóc tách cú pháp & tạo chữ ký HMAC HTC->>Webhook: POST https://yourdomain.com/webhook (JSON payload + X-HiTechCloud-Signature) Webhook->>Webhook: Kiểm tra chữ ký HMAC-SHA256 & Timestamp Webhook->>DB: INSERT IGNORE giao dịch & Cập nhật đơn hàng PAID Webhook-->>HTC: HTTP 200 {"success": true} Note over HTC,Webhook: Nếu HTTP khác 200/timeout -> HTC tự động Retry theo lịch ``` ## Sơ đồ gửi, xác thực & gửi lại ## Danh mục tài liệu - [Bắt đầu nhanh](/pay-webhooks/bat-dau-nhanh) — Thiết lập endpoint và kiểm tra với giao dịch thật. - [Tích hợp Webhook & Payload](/pay-webhooks/tich-hop-webhook) — Cấu trúc dữ liệu JSON, chuẩn phản hồi và kỹ thuật chống trùng lặp. - [Xác thực Webhook](/pay-webhooks/xac-thuc) — So sánh chi tiết 4 cơ chế bảo mật (HMAC, API Key, OAuth 2.0). - [Bảo mật & Whitelist IP](/pay-webhooks/bao-mat) — Danh sách dải IP máy chủ gửi tin và các thực hành an toàn. - [Xử lý lỗi & Lịch Retry](/pay-webhooks/xu-ly-loi) — Quản lý webhook thất bại và cơ chế gửi lại tự động. --- # Bắt đầu nhanh với HiTechCloud Pay Webhooks Bắt đầu nhanh webhook HiTechCloud Pay trong ba bước: viết endpoint tiếp nhận, tạo cấu hình trên bảng điều khiển và thử nghiệm bằng giao dịch thực tế. Chỉ mất 5 phút để kết nối hệ thống của bạn với nguồn thông báo tiền về tự động của HiTechCloud Pay. ## Bước 1: Viết endpoint nhận webhook trên Server của bạn Endpoint là một URL công khai (bắt buộc giao thức HTTPS trên môi trường Production) lắng nghe HTTP POST từ HiTechCloud Pay. ```php false, 'message' => 'Invalid webhook payload']); exit; } // Xử lý đơn hàng: Ghi nhận log giao dịch theo $payload['id'] $transaction_id = $payload['id']; $amount = $payload['transferAmount']; $order_code = $payload['code']; // Phản hồi HTTP 200 kèm {"success": true} header('Content-Type: application/json'); http_response_code(200); echo json_encode(['success' => true]); ``` ```php all(); $transId = $payload['id'] ?? null; if (!$transId) { return response()->json(['success' => false, 'message' => 'Missing ID'], 400); } // Chống xử lý trùng lặp bằng database transaction DB::transaction(function () use ($payload) { $existing = DB::table('payment_logs')->where('transaction_id', $payload['id'])->lockForUpdate()->first(); if ($existing) { return; } DB::table('payment_logs')->insert([ 'transaction_id' => $payload['id'], 'gateway' => $payload['gateway'], 'account_number' => $payload['accountNumber'], 'amount' => $payload['transferAmount'], 'code' => $payload['code'], 'content' => $payload['content'], 'created_at' => now(), ]); // Cập nhật trạng thái đơn hàng nếu khớp mã code if (!empty($payload['code'])) { DB::table('orders')->where('code', $payload['code'])->update(['status' => 'PAID']); } }); return response()->json(['success' => true]); } } ``` ```javascript const express = require('express'); const app = express(); app.use(express.json()); app.post('/api/hitechcloud-webhook', async (req, res) => { const transaction = req.body; console.log('Nhận giao dịch tiền về:', transaction.transferAmount, 'VNĐ'); console.log('Nội dung chuyển khoản:', transaction.content); // 1. Kiểm tra trường bắt buộc if (!transaction.id) { return res.status(400).json({ success: false, message: 'Missing transaction id' }); } // 2. Xử lý đơn hàng... // 3. Bắt buộc phản hồi HTTP 200 kèm success: true return res.status(200).json({ success: true }); }); app.listen(3000, () => console.log('Webhook server running on port 3000')); ``` ```python from fastapi import FastAPI, Request, HTTPException from pydantic import BaseModel from typing import Optional app = FastAPI() class WebhookPayload(BaseModel): id: int gateway: str transactionDate: str accountNumber: str subAccount: Optional[str] = None code: Optional[str] = None content: str transferType: str transferAmount: int accumulated: Optional[int] = 0 referenceCode: Optional[str] = None @app.post("/api/hitechcloud-webhook") async def receive_webhook(payload: WebhookPayload): print(f"Nhận giao dịch #{payload.id} - {payload.transferAmount} VNĐ: {payload.content}") # Xử lý cập nhật CSDL return {"success": True} ``` ```go package main import ( "net/http" "github.com/gin-gonic/gin" ) type WebhookPayload struct { ID int64 `json:"id"` Gateway string `json:"gateway"` TransactionDate string `json:"transactionDate"` AccountNumber string `json:"accountNumber"` Code string `json:"code"` Content string `json:"content"` TransferAmount int64 `json:"transferAmount"` } func main() { r := gin.Default() r.POST("/api/hitechcloud-webhook", func(c *gin.Context) { var payload WebhookPayload if err := c.ShouldBindJSON(&payload); err != nil { c.JSON(http.StatusBadRequest, gin.H{"success": false, "message": "Invalid JSON"}) return } // Xử lý đơn hàng c.JSON(http.StatusOK, gin.H{"success": true}) }) r.Run(":8080") } ``` ```csharp var builder = WebApplication.CreateBuilder(args); var app = builder.Build(); app.MapPost("/api/hitechcloud-webhook", async (HttpContext context) => { var payload = await context.Request.ReadFromJsonAsync(); if (payload == null || payload.Id == 0) { return Results.BadRequest(new { success = false, message = "Invalid payload" }); } // Xử lý ghi nhận giao dịch vào CSDL return Results.Ok(new { success = true }); }); app.Run(); public record HiTechCloudWebhookPayload( long Id, string Gateway, string TransactionDate, string AccountNumber, string? SubAccount, string? Code, string Content, string TransferType, long TransferAmount, long Accumulated, string? ReferenceCode ); ``` ## Bước 2: Tạo Webhook trên bảng điều khiển 1. Đăng nhập vào `https://my.hitechcloud.vn` → chọn mục **Webhooks**. 2. Bấm nút **Thêm Webhook** và điền các trường: 3. • **Tên**: Đặt tên gợi nhớ cho hệ thống tiếp nhận (ví dụ: Website Bán Hàng). 4. • **URL Webhook**: Điền URL endpoint bạn vừa deploy ở bước 1. 5. • **Loại giao dịch**: Chọn 'Tiền vào' hoặc 'Tất cả'. 6. • **Tài khoản áp dụng**: Chọn tất cả tài khoản ngân hàng hoặc từng tài khoản cụ thể. 7. • **Phương thức xác thực**: Khuyến nghị chọn **HMAC-SHA256** để bảo vệ toàn vẹn dữ liệu. 8. Bấm nút **Gửi thử (Test Ping)**. Nếu kết quả hiện 'Thành công' nghĩa là URL của bạn đã sẵn sàng. ## Bước 3: Thử nghiệm với giao dịch thật Thực hiện chuyển một khoản tiền nhỏ (ví dụ 10.000 VNĐ) vào tài khoản ngân hàng của bạn. Trong 1-3 giây, HiTechCloud Pay sẽ tự động gửi webhook chứa dữ liệu giao dịch đến endpoint của bạn. Bạn có thể kiểm tra tab 'Lịch sử gửi' trên my.hitechcloud.vn để xem chi tiết mã phản hồi HTTP và payload. --- # Cấu trúc Payload & Tích hợp Webhook Tích hợp webhook HiTechCloud Pay: đặc tả các trường trong payload giao dịch, quy chuẩn phản hồi bắt buộc và kỹ thuật chống trùng lặp (idempotent). Mỗi khi phát sinh giao dịch thỏa mãn điều kiện, HiTechCloud Pay gửi request HTTP POST dạng JSON đến URL đã cấu hình. ## Cấu trúc Payload mẫu (JSON) ```json { "id": 92704, "gateway": "Vietcombank", "transactionDate": "2026-10-31 09:22:10", "accountNumber": "9988776655", "subAccount": "VA001", "code": "DH98765", "content": "DH98765 chuyen tien mua hosting hitechcloud", "transferType": "in", "description": "NGUYEN VAN A chuyen tien", "transferAmount": 500000, "accumulated": 15500000, "referenceCode": "FT261031998888" } ``` ```json { "id": 92705, "gateway": "MBBank", "transactionDate": "2026-10-31 09:25:40", "accountNumber": "090912345678", "subAccount": null, "code": "INV-7788", "content": "INV-7788 THANH TOAN CLOUD VPS", "transferType": "in", "description": "MBB-090912345678-TK-NAP-TIEN", "transferAmount": 1200000, "accumulated": 48200000, "referenceCode": "MB26103100124" } ``` ## Ý nghĩa chi tiết các trường dữ liệu | Trường | Kiểu | Có thể null? | Mô tả chi tiết | | --- | --- | --- | --- | | `id` | integer | Không | ID duy nhất của giao dịch trên hệ thống HiTechCloud Pay. Giá trị này cố định qua mọi lần retry/replay, dùng làm khóa chống trùng lặp. | | `gateway` | string | Không | Tên ngân hàng phát sinh giao dịch (ví dụ: Vietcombank, MBBank, ACB, BIDV, Techcombank, VPBank...). | | `transactionDate` | string | Không | Thời gian giao dịch theo định dạng `YYYY-MM-DD HH:mm:ss` (múi giờ Việt Nam GMT+7). | | `accountNumber` | string | Không | Số tài khoản ngân hàng thụ hưởng nhận tiền của bạn. | | `subAccount` | string | Có thể rỗng | Số tài khoản ảo (VA) hoặc mã định danh phụ nếu giao dịch thông qua Virtual Account. | | `code` | string | Có thể null | Mã thanh toán bóc tách được từ nội dung theo mẫu cấu hình (ví dụ: `DH98765`). `null` nếu không khớp cấu hình. | | `content` | string | Không | Nội dung chuyển khoản nguyên bản nhận từ ngân hàng, giữ nguyên không biến đổi. | | `transferType` | string | Không | Chiều dòng tiền: `in` (tiền vào) hoặc `out` (tiền ra). | | `description` | string | Có thể rỗng | Mô tả chi tiết giao dịch từ hệ thống ngân hàng. | | `transferAmount` | integer | Không | Số tiền giao dịch thực tế tính bằng VNĐ (luôn là số nguyên dương). | | `accumulated` | integer | Có thể 0 | Số dư tích lũy sau giao dịch (nếu ngân hàng hỗ trợ trả số dư). | | `referenceCode` | string | Có thể rỗng | Mã số bút toán / mã tham chiếu từ ngân hàng chuyển mạch (FT code). | ## 3 Điều kiện bắt buộc để xác nhận thành công 1. **HTTP Status Code**: Server của bạn phải trả về HTTP `200` hoặc `201`. 2. **Body JSON**: Nội dung trả lời phải là chuỗi JSON: `{"success": true}`. 3. **Thời gian timeout**: Máy chủ phải phản hồi trong vòng tối đa **30 giây** (khuyến nghị dưới 2 giây). ## Xử lý chống trùng lặp (Idempotency) Do cơ chế retry tự động khi mạng chập chờn hoặc khi quản trị viên bấm 'Gửi lại' trên bảng điều khiển, một giao dịch có thể được gửi nhiều hơn một lần. Để tránh cộng tiền 2 lần cho khách, bạn phải sử dụng trường `id` của payload làm ràng buộc `UNIQUE` trong cơ sở dữ liệu. ```sql CREATE TABLE `hitechcloud_webhook_transactions` ( `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, `htc_transaction_id` BIGINT UNSIGNED NOT NULL, `gateway` VARCHAR(64) NOT NULL, `transaction_date` DATETIME NOT NULL, `account_number` VARCHAR(64) NOT NULL, `sub_account` VARCHAR(64) NULL, `code` VARCHAR(128) NULL, `content` TEXT NOT NULL, `transfer_type` ENUM('in', 'out') NOT NULL DEFAULT 'in', `transfer_amount` BIGINT UNSIGNED NOT NULL, `accumulated` BIGINT UNSIGNED DEFAULT 0, `reference_code` VARCHAR(128) NULL, `raw_payload` JSON NULL, `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY `uniq_htc_trans_id` (`htc_transaction_id`), INDEX `idx_code` (`code`), INDEX `idx_account` (`account_number`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; ``` ```php prepare("INSERT IGNORE INTO hitechcloud_webhook_transactions (htc_transaction_id, gateway, transaction_date, account_number, sub_account, code, content, transfer_type, transfer_amount, accumulated, reference_code, raw_payload) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"); $stmt->execute([ $trans_id, $payload['gateway'], $payload['transactionDate'], $payload['accountNumber'], $payload['subAccount'] ?? null, $payload['code'] ?? null, $payload['content'], $payload['transferType'], $payload['transferAmount'], $payload['accumulated'] ?? 0, $payload['referenceCode'] ?? null, json_encode($payload) ]); if ($stmt->rowCount() === 0) { // Đã tồn tại giao dịch này trước đó -> phản hồi thành công ngay để dừng retry echo json_encode(['success' => true, 'message' => 'Already processed']); exit; } // Xử lý cộng tiền hoặc kích hoạt dịch vụ cho giao dịch mới... echo json_encode(['success' => true]); ``` --- # Xác thực Webhook HiTechCloud Pay Xác thực webhook HiTechCloud Pay: so sánh và hướng dẫn lập trình các phương thức ký HMAC-SHA256, khoá API, OAuth 2.0 Client Credentials và No Auth. Để đảm bảo các request webhook gửi tới endpoint thực sự xuất phát từ HiTechCloud Pay chứ không phải kẻ xấu giả mạo, HiTechCloud Pay hỗ trợ 4 cơ chế bảo mật xác thực linh hoạt. ## Bảng so sánh phương thức xác thực | Phương thức | Độ bảo mật | Độ phức tạp | Khuyến nghị áp dụng | | --- | --- | --- | --- | | **HMAC-SHA256** | Tối đa | Trung bình | Khuyến nghị cao nhất cho Production. Bảo vệ toàn vẹn dữ liệu và chống tấn công Replay. | | **API Key** | Trung bình | Rất dễ | Phù hợp xác thực cơ bản, truyền header `Authorization: Apikey {KEY}`. | | **OAuth 2.0** | Tối đa | Nâng cao | Dành cho hệ sinh thái doanh nghiệp lớn đã tích hợp máy chủ OAuth Server nội bộ. | | **Không xác thực** | Thấp | Dễ nhất | Chỉ sử dụng trong môi trường thử nghiệm cục bộ / local development. | ## Cơ chế xác thực HMAC-SHA256 (Khuyến nghị) HiTechCloud Pay sẽ ký từng request bằng một chuỗi chữ ký số và gửi kèm hai HTTP header: | Header | Ý nghĩa | | --- | --- | | `X-HiTechCloud-Signature` | Chữ ký số có định dạng: `sha256={hex_hash}` | | `X-HiTechCloud-Timestamp` | Thời điểm gửi webhook tính bằng Unix Timestamp (giây) | ## Công thức tạo chữ ký HMAC của HiTechCloud Pay 1. Lấy giá trị timestamp hiện tại. 2. Ghép chuỗi ký theo định dạng: `{timestamp}.{raw_body}` (sử dụng raw byte dữ liệu gốc của body). 3. Tính giá trị băm HMAC với thuật toán SHA-256 sử dụng khóa bí mật `SECRET_KEY` cấu hình trên webhook. 4. Gửi chữ ký kèm request qua header `X-HiTechCloud-Signature: sha256={hash}`. ```php 300) { http_response_code(401); echo json_encode(['success' => false, 'message' => 'Timestamp expired or invalid']); exit; } // 2. Tái tạo chữ ký số $signed_payload = $timestamp . '.' . $raw_body; $expected_signature = 'sha256=' . hash_hmac('sha256', $signed_payload, $secret); // 3. So sánh an toàn tránh Timing Attack if (!hash_equals($expected_signature, $signature)) { http_response_code(401); echo json_encode(['success' => false, 'message' => 'Invalid signature']); exit; } // Chữ ký hợp lệ -> Xử lý dữ liệu echo json_encode(['success' => true]); ``` ```javascript const crypto = require('crypto'); function verifyHiTechCloudWebhook(req, secret) { const sigHeader = req.headers['x-hitechcloud-signature']; const tsHeader = req.headers['x-hitechcloud-timestamp']; if (!sigHeader || !tsHeader) return false; const timestamp = parseInt(tsHeader, 10); const now = Math.floor(Date.now() / 1000); // Chống replay trong khoảng 5 phút if (Math.abs(now - timestamp) > 300) return false; // Lấy raw body dạng chuỗi const rawBody = typeof req.body === 'string' ? req.body : JSON.stringify(req.body); const signedData = `${timestamp}.${rawBody}`; const expectedSig = 'sha256=' + crypto.createHmac('sha256', secret).update(signedData).digest('hex'); return crypto.timingSafeEqual(Buffer.from(sigHeader), Buffer.from(expectedSig)); } ``` ```python import hmac import hashlib import time def verify_hitechcloud_signature(raw_body: bytes, sig_header: str, ts_header: str, secret: str) -> bool: if not sig_header or not ts_header: return False try: timestamp = int(ts_header) except ValueError: return False # Chống replay attack trong 5 phút if abs(time.time() - timestamp) > 300: return False signed_payload = f"{timestamp}.".encode('utf-8') + raw_body expected_sig = "sha256=" + hmac.new( secret.encode('utf-8'), signed_payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(sig_header, expected_sig) ``` ## Cơ chế xác thực API Key Khi cấu hình API Key, HiTechCloud Pay sẽ gửi kèm header `Authorization: Apikey YOUR_API_KEY` (hoặc `X-API-Key: YOUR_API_KEY`). Máy chủ của bạn chỉ cần kiểm tra xem giá trị này có khớp với key đã thiết lập hay không. ```php false, 'message' => 'Unauthorized']); exit; } ``` ## Cơ chế xác thực OAuth 2.0 (Client Credentials) HiTechCloud Pay hỗ trợ gọi vào máy chủ OAuth của bạn để xin Bearer Token (`POST /oauth/token` với `client_id` và `client_secret`) trước khi bắn webhook. Token được lưu cache và tái sử dụng cho đến khi hết hạn. --- # HiTechCloud Pay API HiTechCloud Pay API: bộ REST API truy vấn tài khoản ngân hàng doanh nghiệp, giao dịch, số dư và quản lý tài khoản ảo (Virtual Account) với phản hồi JSON chuẩn. HiTechCloud Pay API là giao diện lập trình ứng dụng RESTful cho phép các hệ thống ERP, CRM, phần mềm kế toán và website thương mại điện tử kết nối trực tiếp với tài khoản ngân hàng. Với HiTechCloud Pay API, bạn có thể tự động hóa hoàn toàn quy trình kiểm tra số dư, trích xuất sao kê, theo dõi giao dịch và quản lý hệ thống tài khoản ảo. ## Sơ đồ kết nối ## Các tính năng chính - **Quản lý tài khoản ngân hàng**: Lấy danh sách tài khoản liên kết, tên chủ tài khoản, ngân hàng, số dư hiện tại và trạng thái hoạt động. - **Truy vấn lịch sử giao dịch**: Lấy danh sách giao dịch thu/chi với bộ lọc đa chiều (theo thời gian, số tiền, từ khóa nội dung, số tài khoản). - **Chi tiết giao dịch thời gian thực**: Tra cứu chính xác từng bút toán qua định danh duy nhất UUID. - **Quản lý tài khoản ảo (Virtual Account)**: Cấp phát và theo dõi tài khoản định danh riêng cho từng khách hàng hoặc đơn hàng (hỗ trợ Vietcombank, BIDV, Sacombank, Shinhan Bank, VPBank...). ## Môi trường và Base URLs | Môi trường | Base URL | Mô tả | | --- | --- | --- | | Production (Chính thức) | `https://userapi.hitechcloud.vn` | Truy vấn tài khoản và giao dịch thật | | Sandbox (Thử nghiệm) | `https://userapi-sandbox.hitechcloud.vn` | Môi trường test với dữ liệu mô phỏng độc lập | ## Định dạng phản hồi Envelope Tất cả phản hồi từ HiTechCloud Pay API đều tuân theo cấu trúc JSON Envelope chuẩn mực: ```json { "status": "success", "data": [], "meta": { "pagination": { "total": 100, "per_page": 20, "current_page": 1, "last_page": 5, "has_more": true } } } ``` ## Danh mục tài liệu - [Bắt đầu nhanh](/pay-api/v2/bat-dau-nhanh) — Cấp token và gọi API đầu tiên. - [Xác thực & Rate Limit](/pay-api/v2/xac-thuc) — Bearer Token và giới hạn tần suất. - [Môi trường Sandbox](/pay-api/v2/sandbox) — Môi trường thử nghiệm giả lập. - [API Tài khoản ngân hàng](/pay-api/v2/tai-khoan-ngan-hang) — Quản lý tài khoản liên kết. - [API Giao dịch ngân hàng](/pay-api/v2/giao-dich) — Lấy lịch sử biến động số dư. - [API Tài khoản ảo (VA)](/pay-api/v2/tai-khoan-ao) — Cấp phát số tài khoản định danh. --- # Bắt đầu nhanh với HiTechCloud Pay API Bắt đầu nhanh HiTechCloud Pay API: tạo access token và gọi yêu cầu đầu tiên để lấy danh sách tài khoản ngân hàng và giao dịch chỉ trong năm phút. Hướng dẫn từng bước giúp bạn kết nối và đọc dữ liệu giao dịch ngân hàng thông qua HiTechCloud Pay API. ## Bước 1: Tạo API Token 1. Đăng nhập vào cổng quản trị `https://my.hitechcloud.vn`. 2. Truy cập menu **Cấu hình Công ty** → chọn **API Access** (hoặc truy cập trực tiếp `https://my.hitechcloud.vn/companyapi`). 3. Nhấn **+ Thêm API mới**, nhập tên ứng dụng và bấm Tạo. 4. Hệ thống hiển thị mã **API Token**. Sao chép và lưu trữ mã token cẩn thận trong biến môi trường. > API Token đại diện cho quyền truy cập dữ liệu tài chính của bạn. Tuyệt đối không để lộ token trong mã nguồn frontend (JavaScript, Mobile App) và không commit lên kho mã nguồn công khai (Git). ## Bước 2: Lấy danh sách tài khoản ngân hàng Gọi endpoint `GET /v2/bank-accounts` để lấy danh sách các tài khoản ngân hàng đã được liên kết: ```bash curl -X GET "https://userapi.hitechcloud.vn/v2/bank-accounts" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```php Token có thời gian sống (TTL) là 6000 giây (100 phút). Hãy lưu token vào bộ nhớ đệm (cache) và tái sử dụng cho các lệnh phát thanh tiếp theo. ## Bước 2: Kiểm tra thiết bị loa Sử dụng mã số `hardwareId` in dưới đáy loa (ví dụ: `HTC_S5_2508000001`) để kiểm tra trạng thái: ```bash curl -X POST "https://speaker-api.hitechcloud.vn/devices/v1/speaker/pair/check" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"hardwareId": "HTC_S5_2508000001"}' ``` ```json { "code": 200, "message": "Thành công", "data": { "hardwareId": "HTC_S5_2508000001", "model": "HiTechCloud SoundBox S5 Plus", "isPaired": false, "online": true } } ``` ## Bước 3: Ghép nối thiết bị và Xác thực OTP 1. **Bật chế độ ghép nối**: Nhấn giữ nút nguồn/ghép nối trên thân loa trong 3 giây cho đến khi loa phát âm thanh báo hiệu. 2. **Yêu cầu ghép nối**: Gọi `POST /devices/v1/speaker/pair/request` với `hardwareId`. Loa sẽ phát ra giọng nói đọc to 4 chữ số OTP ngẫu nhiên (ví dụ: 'Mã xác thực của bạn là: 8 9 2 1') và trả về `session_id`. 3. **Xác thực OTP**: Gọi `POST /devices/v1/speaker/pair/verify` gửi kèm `hardwareId`, `session_id` và mã `otp`. Loa sẽ thông báo 'Ghép nối thành công'. ```bash curl -X POST "https://speaker-api.hitechcloud.vn/devices/v1/speaker/pair/verify" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "hardwareId": "HTC_S5_2508000001", "session_id": "8b9f6d2a-3c1b-4f7a-a7d4-123456789abc", "otp": "8921" }' ``` ## Bước 4: Bắn thông báo biến động số dư (Đọc số tiền) Khi hệ thống ghi nhận khách đã thanh toán, hãy gọi API này để loa ngay lập tức đọc to số tiền: ```bash curl -X POST "https://speaker-api.hitechcloud.vn/devices/v1/speaker/transactions/notify" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "hardwareId": "HTC_S5_2508000001", "amount": 250000, "requestId": "TXN_20250515_00099" }' ``` ```json { "code": 200, "message": "Đã gửi thông báo thành công", "data": { "hardwareId": "HTC_S5_2508000001", "requestId": "TXN_20250515_00099", "status": "SENT" } } ``` > Trường `requestId` bắt buộc phải là duy nhất cho mỗi giao dịch. Nếu bạn gửi trùng `requestId`, loa sẽ tự động bỏ qua để tránh phát âm thanh trùng lặp. --- # Hoá đơn điện tử — HiTechCloud Pay eInvoice Hoá đơn điện tử HiTechCloud Pay: phát hành và quản lý HĐĐT tự động theo Nghị định 123/2020/NĐ-CP và Thông tư 78/2021/TT-BTC, kết nối trực tiếp Cơ quan Thuế qua REST API. HiTechCloud Pay eInvoice API là giải pháp tự động hóa toàn diện quy trình xuất hóa đơn điện tử dành cho doanh nghiệp và nền tảng thương mại. Ngay sau khi đơn hàng được thanh toán, hệ thống có thể tự động lập, ký số và truyền dữ liệu hóa đơn có mã hoặc không có mã lên hệ thống hóa đơn điện tử của Tổng cục Thuế Việt Nam. ## Sơ đồ kết nối ## Tuân thủ pháp lý & Tính năng nổi bật - **Chuẩn pháp lý 100%**: Hoàn toàn tuân thủ Nghị định 123/2020/NĐ-CP và Thông tư 78/2021/TT-BTC của Bộ Tài chính. - **Kết nối đa nhà cung cấp**: Tương thích và tích hợp sâu với các nhà cung cấp giải pháp HĐĐT hàng đầu: Mắt Bão, Viettel, VNPT, MISA, BKAV, v.v. - **Tự động hóa theo thanh toán**: Tự động kích hoạt xuất hóa đơn ngay khi nhận được tín hiệu thanh toán thành công từ Cổng thanh toán hoặc Webhook. - **Tải file gốc tức thì**: Cung cấp link tải file PDF thể hiện và file XML có chữ ký số gốc để gửi cho khách hàng và lưu trữ theo luật kế toán. ## Môi trường và Base URLs | Môi trường | Base URL | | --- | --- | | Production (Chính thức) | `https://einvoice-api.hitechcloud.vn` | | Sandbox (Thử nghiệm) | `https://einvoice-api-sandbox.hitechcloud.vn` | ## Quy trình 4 bước phát hành 1. **Lấy Access Token**: Dùng `client_id` và `client_secret` qua Basic Auth để nhận Bearer Token (thời hạn 24 giờ). 2. **Chọn tài khoản nhà cung cấp**: Tra cứu `provider_account_id`, mẫu số và ký hiệu hóa đơn đang hoạt động. 3. **Tạo và phát hành hóa đơn**: Gửi payload thông tin bên mua và danh mục hàng hóa (`POST /v1/invoices/create`), nhận `tracking_code` bất đồng bộ. 4. **Kiểm tra trạng thái CQT**: Polling kiểm tra kết quả duyệt mã của Cơ quan Thuế và lấy link tải file PDF/XML. --- # Bắt đầu nhanh với HiTechCloud Pay eInvoice API Bắt đầu nhanh Hoá đơn điện tử HiTechCloud Pay: phát hành hoá đơn đầu tiên lên Cơ quan Thuế trong bốn bước, kèm mã mẫu cURL. Tài liệu hướng dẫn từng bước gọi API phát hành hóa đơn điện tử tự động. ## Bước 1: Lấy Access Token Gọi endpoint `/v1/token` với HTTP Basic Auth để lấy `access_token`: ```bash curl -X POST "https://einvoice-api.hitechcloud.vn/v1/token" \ -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" ``` ```json { "success": true, "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 86400 } } ``` ## Bước 2: Lấy danh sách tài khoản nhà cung cấp Gọi endpoint `/v1/provider-accounts` để lấy danh sách các tài khoản nhà cung cấp HĐĐT đã liên kết: ```bash curl -X GET "https://einvoice-api.hitechcloud.vn/v1/provider-accounts?page=1&per_page=20" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ```json { "data": { "paging": { "per_page": 20, "total": 1, "current_page": 1, "page_count": 1 }, "items": [ { "id": "0aea3134-da40-11f0-aef4-52c7e9b4f41b", "provider": "matbao", "active": true, "tax_authority_approved_date": "2026-04-20" } ] } } ``` ## Bước 3: Tạo và phát hành hóa đơn điện tử Gọi endpoint `/v1/invoices/create` với `is_draft: false` để phát hành và nộp ngay lên Cơ quan Thuế: ```bash curl -X POST "https://einvoice-api.hitechcloud.vn/v1/invoices/create" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "template_code": "1", "invoice_series": "C26TSE", "issued_date": "2026-01-26 00:00:00", "currency": "VND", "provider_account_id": "0aea3134-da40-11f0-aef4-52c7e9b4f41b", "reference_code": "HD-2026-0001", "payment_method": "TM/CK", "is_draft": false, "buyer": { "type": "enterprise", "name": "Công ty TNHH Giải Pháp Công Nghệ Mới", "legal_name": "CÔNG TY TNHH GIẢI PHÁP CÔNG NGHỆ MỚI", "tax_code": "0109988776", "address": "Số 123 Đường Công Nghệ, Hà Nội", "email": "ketoan@example.com", "phone": "0988000111" }, "items": [ { "name": "Dịch vụ Điện toán đám mây HiTechCloud VPS Pro", "unit": "Tháng", "quantity": 1, "unit_price": 500000, "tax_rate": "10%", "amount": 500000 } ] }' ``` ```json { "success": true, "data": { "tracking_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b", "tracking_url": "https://einvoice-api.hitechcloud.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b", "message": "Đã tạo yêu cầu xuất bán hóa đơn điện tử" } } ``` ## Bước 4: Kiểm tra trạng thái ký số và duyệt CQT Thực hiện gọi kiểm tra trạng thái bằng mã `tracking_code` sau 2-3 giây: ```bash curl -X GET "https://einvoice-api.hitechcloud.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ```json { "success": true, "data": { "reference_code": "HD-2026-0001", "status": "Success", "message": "Xuất hóa đơn điện tử thành công", "invoice": { "invoice_number": "00001234", "issued_date": "2026-01-26", "pdf_url": "https://einvoice-api.hitechcloud.vn/v1/invoices/view/HD-2026-0001.pdf", "xml_url": "https://einvoice-api.hitechcloud.vn/v1/invoices/view/HD-2026-0001.xml", "status": "approved", "total_before_tax": 500000, "tax_amount": 50000, "total_amount": 550000 } } } ``` --- # Open Banking — HiTechCloud Pay BankHub Open Banking HiTechCloud Pay (BankHub): kết nối trực tiếp hơn 50 ngân hàng tại Việt Nam qua giao diện Hosted Link, nhúng iFrame/WebView và đồng bộ giao dịch tự động. HiTechCloud Pay BankHub là giải pháp Open Banking thế hệ mới tại Việt Nam, cho phép các ứng dụng tài chính (Fintech), phần mềm quản trị doanh nghiệp (ERP), nền tảng kế toán và sàn giao dịch kết nối an toàn với tài khoản ngân hàng của người dùng thông qua luồng xác thực Hosted Link chuẩn quốc tế (tương tự mô hình Plaid). ## Sơ đồ kết nối ## Các năng lực chính - **Giao diện kết nối Hosted Link**: Người dùng đăng nhập và ủy quyền tài khoản ngân hàng thông qua giao diện web bảo mật chuẩn ngân hàng. - **Hỗ trợ nhúng đa nền tảng**: Dễ dàng tích hợp vào Website (iFrame), Ứng dụng di động (WebView trên React Native, Flutter, iOS, Android). - **Lắng nghe sự kiện thời gian thực (PostMessage)**: Bắt các sự kiện liên kết thành công, hủy bỏ hoặc hết hạn phiên qua `window.postMessage`. - **Đồng bộ sao kê & Webhook tự động**: Tự động nhận biến động số dư tức thời từ tài khoản ngân hàng đã liên kết qua kênh IPN riêng biệt. ## Môi trường và Base URLs | Mục | Môi trường Production | Môi trường Sandbox | | --- | --- | --- | | Host API | `https://bankhub-api.hitechcloud.vn` | `https://bankhub-api-sandbox.hitechcloud.vn` | | Host Giao diện (Hosted Link) | `https://bankhub.hitechcloud.vn` | `https://bankhub-sandbox.hitechcloud.vn` | ## Quy trình tích hợp 3 bước 1. **Lấy Access Token**: Gọi `POST /v1/token` từ backend server của bạn. 2. **Tạo Link Token**: Gọi `POST /v1/link-token/create` để sinh ra một đường link kết nối `hosted_link_url` duy nhất. 3. **Nhúng giao diện & Nhận sự kiện**: Mở `hosted_link_url` trong iFrame hoặc WebView và lắng nghe sự kiện hoàn tất. --- # Bắt đầu nhanh với HiTechCloud Pay BankHub Bắt đầu nhanh Open Banking BankHub của HiTechCloud Pay trong ba bước: lấy access token, tạo Hosted Link và nhúng iFrame để nhận sự kiện liên kết. Tài liệu hướng dẫn triển khai luồng liên kết ngân hàng cho ứng dụng của bạn. ## Bước 1: Lấy Access Token Gọi API từ backend server bằng HTTP Basic Auth với `client_id` và `client_secret` do HiTechCloud Pay cấp: ```bash curl -X POST "https://bankhub-api.hitechcloud.vn/v1/token" \ -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \ -H "Content-Type: application/x-www-form-urlencoded" ``` ```json { "code": 201, "access_token": "36483db493b10304eb3abc143b3593fa1473eb9b", "ttl": 60000 } ``` ## Bước 2: Tạo Link Token & Hosted Link URL Sử dụng `access_token` để tạo một phiên liên kết mới cho khách hàng: ```bash curl -X POST "https://bankhub-api.hitechcloud.vn/v1/link-token/create" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "company_xid": "850e8400-e29b-41d4-a716-446655440000", "purpose": "LINK_BANK_ACCOUNT", "completion_redirect_uri": "https://example.com/bank/linked-success" }' ``` ```json { "xid": "850e8400-e29b-41d4-a716-446655440000", "hosted_link_url": "https://bankhub.hitechcloud.vn/link/850e8400-e29b-41d4-a716-446655440000", "link_token": "950e8400-e29b-41d4-a716-446655440000", "expires_at": "2025-05-15 15:30:00" } ``` ## Bước 3: Nhúng iFrame và Xử lý PostMessage Events Nhúng `hosted_link_url` vào website của bạn và đăng ký hàm lắng nghe sự kiện: ```html ``` --- # API Reference Danh mục toàn bộ sản phẩm API của HiTechCloud Developers — Pay, eKYC, Omnichannel, POS, CRM, WAF, Sale AI — kèm tổng quan, endpoint, sơ đồ kết nối và mã mẫu. ## Sản phẩm - **HiTechCloud Pay** — Cổng thanh toán VietQR/NAPAS 247, thẻ quốc tế, webhook, Pay API, loa thông báo, hoá đơn điện tử, Open Banking. (/cong-thanh-toan) - **HiTechCloud eKYC** — Xác thực VNeID/eID: eKYC, đọc chip CCCD, so khớp khuôn mặt, chia sẻ dữ liệu C06. (/ekyc-vneid/tong-quan) - **HiTechCloud Omnichannel** — Hợp nhất hội thoại Facebook, Instagram, Zalo, TikTok, web widget về một API. (/omnichannel/tong-quan) - **HiTechPos** — Bán hàng đa kênh: đơn hàng, sản phẩm, tồn kho, kho, khuyến mãi, sổ quỹ, báo cáo. (/pos/tong-quan) - **HiTechCloud CRM** — Quản lý liên hệ, công ty, cơ hội, pipeline, báo giá và tự động hoá bán hàng. (/crm/tong-quan) - **HiTechCloud WAF** — Tường lửa ứng dụng web: site, chính sách, chống bot, SSL, giám sát tấn công. (/waf/tong-quan) - **HiTechCloud Sale AI** — Chatbot bán hàng: kịch bản, từ khoá, broadcast, trợ lý AI, đơn hàng từ hội thoại. (/sale-ai/tong-quan) - **HiTechCloud User API** — Quản lý dịch vụ, hoá đơn, tên miền của tài khoản my.hitechcloud.vn. (/user-api) - **API Tools** — Bộ công cụ hạ tầng: tên miền, DNS, mạng, bảo mật, tiện ích cho nhà phát triển. (/api-tools) - **Identity & SSO** — HiTechCloud ID: OAuth2 / OIDC, passkey, đăng nhập một lần cho toàn hệ sinh thái. (/identity) - **HiTechCloud ID (OAuth 2.0 / OIDC)** — Đăng nhập bằng HiTechCloud ID: Authorization Code + PKCE, refresh/revoke, id_token, UserInfo, device flow, token cá nhân. (/hitechcloud-id/tong-quan) - **AI & MCP** — llms.txt, đặc tả OpenAPI và máy chủ MCP để trợ lý AI gọi thẳng API. (/ai-mcp) ## Sơ đồ kết nối Mọi yêu cầu đi qua một lớp xác thực và gateway chung trước khi tới dịch vụ và nhà cung cấp. > Mỗi sản phẩm có đặc tả OpenAPI và máy chủ MCP riêng — xem trang [AI & MCP](/ai-mcp) để tích hợp với trợ lý AI. --- # Webhooks Nhận sự kiện của HiTechCloud qua webhook HTTPS: cảnh báo hạn mức, tạo và thu hồi khoá API, hoá đơn và trạng thái nguồn dữ liệu, kèm khoá ký để xác minh. Webhook là địa chỉ HTTPS của bạn mà hệ thống gọi khi có sự kiện. Tạo và quản lý trong Cổng khách hàng, mục **Webhook**. - Chỉ nhận địa chỉ **HTTPS công khai** — địa chỉ nội bộ, loopback hoặc link-local bị từ chối. - Khoá ký dạng `whsec_…` **chỉ hiện một lần** khi tạo; dùng nó để xác thực nguồn gửi. - Có thể tạm dừng / bật lại một webhook; lịch sử các lần gửi gần nhất hiện trong Cổng khách hàng. ## Sự kiện | Sự kiện | Khi nào | | --- | --- | | `key.created` | Có người tạo khoá mới trong tổ chức. | | `key.revoked` | Một khoá bị thu hồi. | | `key.expiring` | Còn 7 ngày là khoá hết hạn. | | `quota.threshold` | Đã dùng 80% hạn mức tháng. | | `quota.exceeded` | Đã dùng hết hạn mức tháng. | | `source.down` | Một nguồn dữ liệu ngoài ngừng phản hồi. | | `member.joined` | Có người nhận lời mời vào tổ chức. | | `invoice.issued` | Hoá đơn kỳ mới đã lập. | | `access.approved` / `access.denied` | Đơn xin quyền endpoint hạn chế được duyệt / từ chối. | | `announcement.published` | Quản trị hệ thống công bố thông báo. | > Cấu trúc chi tiết của nội dung và header chữ ký sẽ được công bố tại đây khi dịch vụ gửi webhook chính thức mở. --- # Mã lỗi Cách xử lý lỗi của API Tools HiTechCloud: phản hồi JSON ok:false kèm mã error ổn định và message, danh mục mã HTTP (401, 403, 404, 429, 503) và mã lỗi chuỗi. ```json { "ok": false, "error": "invalid_api_key", "message": "Khoá API không đúng. Kiểm tra lại trong portal." } ``` Hãy xử lý theo `error` (ổn định) chứ không theo `message` (có thể đổi lời). ## Mã HTTP | Mã | Ý nghĩa | Cách xử lý | | --- | --- | --- | | 200 | Thành công. | — | | 401 | Thiếu hoặc sai khoá API. | Gửi header `X-API-Key` đúng khoá còn hiệu lực. | | 403 | Khoá không đủ quyền hoặc IP không được phép. | Sửa phạm vi khoá / danh sách IP trong Cổng khách hàng. | | 404 | Không có dữ liệu tương ứng. | Kiểm tra lại giá trị truyền vào; có endpoint dùng 404 để báo “còn trống”. | | 422 | Tham số chưa hợp lệ. | Đọc `message` / `errors` để sửa tham số. | | 429 | Vượt tốc độ hoặc hạn mức. | Chờ theo header `Retry-After` rồi thử lại, hoặc nâng hạn mức. | | 503 | Nguồn dữ liệu hoặc endpoint tạm ngừng. | Thử lại sau (có `Retry-After`); dữ liệu đệm vẫn dùng được. | ## Mã lỗi `error` | Mã | HTTP | Nguyên nhân | | --- | --- | --- | | `missing_api_key` | 401 | Không có header X-API-Key. | | `invalid_api_key` | 401 | Khoá không tồn tại. | | `revoked_api_key` | 401 | Khoá đã bị thu hồi. | | `expired_api_key` | 401 | Khoá đã hết hạn. | | `ip_not_allowed` | 403 | IP gọi không nằm trong danh sách cho phép của khoá. | | `scope_not_allowed` | 403 | Khoá không được cấp nhóm dịch vụ này. | | `admin_key_required` | 403 | Endpoint chỉ dành cho khoá quản trị. | | `endpoint_grant_required` | 403 | Endpoint hạn chế — cần xin quyền riêng. | | `organization_suspended` | 403 | Tổ chức đang bị đình chỉ. | | `owner_banned` / `owner_deleted` | 403 | Chủ khoá bị khoá hoặc đã bị xoá. | | `rate_limit_exceeded` | 429 | Vượt số lượt gọi mỗi phút của khoá. | | `user_rate_limit_exceeded` | 429 | Vượt tốc độ riêng của tài khoản. | | `user_quota_exceeded` | 429 | Hết hạn mức tháng của tài khoản. | | `endpoint_rate_limit_exceeded` | 429 | Endpoint này giới hạn tốc độ riêng. | | `endpoint_disabled` | 503 | Endpoint tạm ngừng phục vụ. | | `target_not_allowed` | 422 | Giá trị truyền vào trỏ tới địa chỉ nội bộ / không được phép. | --- # Changelog Lịch sử phiên bản của các API và tài liệu HiTechCloud Developers: sản phẩm mới, endpoint mới, cải tiến và các thay đổi phá vỡ tương thích được báo trước. Trang này ghi lại các thay đổi của nền tảng API HiTechCloud: sản phẩm mới, endpoint mới, cải tiến và thay đổi phá vỡ tương thích (breaking change). Mục mới nhất ở trên cùng. > Chúng tôi tuân theo [SemVer](https://semver.org): thay đổi phá vỡ tương thích chỉ phát hành ở phiên bản lớn (major) và luôn được báo trước tại đây cùng webhook `announcement.published`. Hãy theo dõi trang này hoặc đăng ký webhook để nhận thông báo. - **Trạng thái API** — Mọi API đang hoạt động ổn định. - **Nhịp phát hành** — Tính năng mới hàng tuần; breaking change báo trước tối thiểu 90 ngày. - **Nhận thông báo** — Đăng ký webhook `announcement.published` để tự động nhận tin. (/webhooks) ## 2026-11-01 · v2.7 ### Bộ SDK đa ngôn ngữ (mã nguồn mở) - Phát hành bộ SDK chính thức trên GitHub (org `hitechcloudvn`) cho Node/TypeScript, Python, PHP, Go và Java: **HiTechCloud SDK** (User API), **Tools SDK**, **VNeID SDK**, **HiTechPos SDK**, **Omnichannel SDK**, **CRM SDK**, **WAF SDK**, **Sale AI SDK** — kèm OpenAPI, ví dụ, máy chủ MCP và CLI. - **Laravel package** `hitechcloudvn/laravel-hitechcloudpay` phủ toàn bộ sản phẩm (Pay, eKYC, POS, Omnichannel, CRM, WAF, Sale AI, Tools, User API): migrations, routes webhook + middleware xác minh chữ ký, events, jobs, facade `HiTechCloud`. Tương thích PHP 8.0+ và Laravel 9–13. - Cài đặt: `composer require hitechcloudvn/laravel-hitechcloudpay`, `npm i @hitechcloudvn/`, `pip install hitechcloud-`. ### Tài liệu SDK & điều hướng - Khu **SDK & Ví dụ** riêng tại [/sdk](/sdk): mỗi bộ SDK có trang tổng quan, cài đặt theo ngôn ngữ, ví dụ, MCP và menu (sidebar) độc lập. - Tách khu SDK khỏi tài liệu API: trang chủ, tài liệu và API Reference không còn lẫn SDK; nút chuyển sản phẩm hiển thị đúng ngữ cảnh (sản phẩm API hoặc bộ SDK). - [API Reference](/reference) liệt kê toàn bộ danh mục sản phẩm kèm sơ đồ kết nối và tìm kiếm trang. ## 2026-10-31 · v2.6 ### Sản phẩm mới - **HiTechCloud WAF** — Tường lửa ứng dụng web (vcwaf): 227 endpoint quản trị site, chính sách, chống bot, SSL, giám sát tấn công, thống kê. Xem [Tổng quan WAF](/waf/tong-quan). - **HiTechCloud Sale AI** — Nền tảng chatbot bán hàng đa kênh: kịch bản, từ khoá, chuỗi tin, broadcast, trợ lý AI, đơn hàng từ hội thoại. Xem [Tổng quan Sale AI](/sale-ai/tong-quan). - **HiTechCloud CRM** — Quản lý liên hệ, công ty, cơ hội, pipeline, báo giá và tự động hoá. Xem [Tổng quan CRM](/crm/tong-quan). - **HiTechPos** — API bán hàng đa kênh: đơn hàng, sản phẩm, tồn kho, kho, khuyến mãi, sổ quỹ, báo cáo. Xem [Tổng quan HiTechPos](/pos/tong-quan). - **HiTechCloud Omnichannel** — Hợp nhất hội thoại Facebook, Instagram, Zalo, TikTok, web về một API. Xem [Tổng quan Omnichannel](/omnichannel/tong-quan). - **HiTechCloud eKYC** — Xác thực VNeID/eID: eKYC, đọc chip CCCD, so khớp khuôn mặt, chia sẻ dữ liệu C06. Xem [Tổng quan eKYC](/ekyc-vneid/tong-quan). ### Cải tiến - Trang chủ tài liệu liệt kê đầy đủ mọi sản phẩm kèm logo và sơ đồ kết nối tổng thể. - Bổ sung sơ đồ kết nối (flow) và logo thương hiệu thật cho các trang sản phẩm. - API playground kiểm thử tại chỗ mở rộng cho toàn bộ máy chủ sản phẩm mới (ekyc, omni, pos, crm, waf, sale-ai và bản sandbox). - Chuẩn hoá thuật ngữ chuyên ngành thống nhất trên toàn bộ tài liệu. ## 2026-10-24 · v2.5 ### HiTechCloud Pay - Ra mắt họ sản phẩm **HiTechCloud Pay**: Cổng thanh toán, Webhooks, Pay API, Loa thông báo, Hoá đơn điện tử và Open Banking. - Thanh toán VietQR / NAPAS 247 và thẻ quốc tế Visa / Mastercard / JCB qua một phiên thanh toán duy nhất. - Webhook ký bằng HMAC-SHA256; hỗ trợ idempotency key và cơ chế thử lại (retry). ### Cải tiến - Bố cục tài liệu API hai cột: mô tả bên trái, mã mẫu dính (sticky) bên phải. - Tô màu cú pháp cho khối mã; nút sao chép và mở bằng AI trên mỗi trang. ## 2026-10-15 · v2.0 ### Nền tảng tài liệu mới - Cổng tài liệu và Cổng khách hàng dựng lại trên nền tảng mới; đăng nhập bằng **HiTechCloud ID**. - Công cụ tra cứu chạy ngay trong Cổng khách hàng, không cần nhập khoá. - Số endpoint và danh mục được đếm trực tiếp từ hệ thống đang chạy. - Thêm máy chủ **MCP**, tệp `llms.txt` và bộ SDK / CLI cho trợ lý AI. ### Thay đổi phá vỡ tương thích - Lỗi chuẩn hoá về dạng `ok:false` + `error` + `message` — xem [Mã lỗi](/ma-loi). - Xác thực chuyển sang khoá API theo phạm vi (scope) và hạn mức theo khoá — xem [Xác thực](/xac-thuc). > Cần lịch sử cũ hơn hoặc nhật ký thay đổi theo từng endpoint? Liên hệ đội hỗ trợ hoặc theo dõi đặc tả OpenAPI của từng sản phẩm. --- # Identity & SSO Identity & SSO của HiTechCloud: đăng nhập một lần bằng HiTechCloud ID, passkey và OAuth2 / OpenID Connect để tích hợp xác thực cho ứng dụng của bạn. HiTechCloud ID là hệ thống danh tính chung: đăng nhập khách hàng và nhân viên, passkey, OAuth2 / OpenID Connect, quản lý hồ sơ. - [Tài liệu API tương tác (Redoc)](https://iam.hitechcloud.vn/api/v1/docs) - [Đặc tả OpenAPI 3.1](https://iam.hitechcloud.vn/api/v1/openapi.json) > Cổng khách hàng này cũng đăng nhập bằng HiTechCloud ID — không cần tài khoản riêng. --- # AI & MCP AI & MCP của HiTechCloud: nạp llms.txt, tải đặc tả OpenAPI hoặc kết nối máy chủ MCP để trợ lý AI đọc tài liệu và gọi thẳng endpoint của bạn. Có ba cách để trợ lý AI hoặc IDE dùng được tài liệu và endpoint của HiTechCloud: - **Đọc tài liệu** — nạp [llms.txt](/tai-lieu/llms.txt) hoặc [gói ngữ cảnh đầy đủ](/tai-lieu/llms-full.txt) vào ngữ cảnh của mô hình. - **Sinh code** — tải đặc tả OpenAPI hoặc bộ Postman rồi để công cụ của bạn sinh client. - **Gọi trực tiếp** — [kết nối MCP](/tai-lieu/mcp): trợ lý tìm và gọi endpoint bằng vài meta-tool thay vì nạp cả trăm tool. Chi tiết từng cách ở trang [AI & LLM](/tai-lieu/ai).