Hướng dẫn kết nối Open API

Tài liệu này sẽ hướng dẫn bạn từng bước đăng ký tài khoản nhà phát triển, xin quyền truy cập từ khách hàng, tích hợp và sử dụng Open API của Gói Hàng Chuẩn.

1. Đăng ký tài khoản đối tác

Để tích hợp API, trước tiên bạn cần đăng ký tài khoản đối tác:

Truy cập: https://goihangchuan.vn/doitac
Điền đầy đủ và chính xác thông tin yêu cầu.
Nhấn "Đăng ký" để hoàn tất.

Sau khi đăng ký thành công, hệ thống sẽ hiển thị các thông tin quan trọng:

Partner ID: Định danh duy nhất cho tài khoản đối tác của bạn.
Webhook Secret: Chuỗi ký tự bí mật dùng để xác thực webhook.

⚠️ Vui lòng lưu lại thông tin này. Chúng tôi sẽ duyệt hồ sơ trong 1-3 ngày làm việc.

2. Xin quyền truy cập API

Sau khi tài khoản đối tác của bạn được duyệt, bước tiếp theo là xin quyền truy cập dữ liệu từ cửa hàng.

Hãy gửi đường dẫn sau cho quản trị viên của cửa hàng mà bạn muốn kết nối: https://goihangchuan.vn/capquyen?partner_id=YOUR_PARTNER_ID

Thay YOUR_PARTNER_ID bằng Partner ID của bạn.

Khi truy cập liên kết, quản trị viên sẽ thực hiện các bước sau:

Chọn cửa hàng muốn cấp quyền.
Xác nhận yêu cầu cấp quyền.

Ngay sau khi hoàn tất, hệ thống sẽ tạo và hiển thị API Key tương ứng.
Bạn có thể sử dụng API Key này để bắt đầu gửi request tới hệ thống Open API.

3. Sử dụng API

3.1. Truy cập tài liệu

Toàn bộ tài liệu REST API có thể được xem tại: https://open.goihangchuan.vn/docs

3.2. Gửi yêu cầu API

Bạn có thể gửi API Key theo một trong ba cách sau (ưu tiên thứ tự từ trên xuống):

Cách 1: Trong Header (`x-api-key`) - Khuyến nghị

GET /shop/detail HTTP/1.1
Host: open.goihangchuan.vn
x-api-key: YOUR_API_KEY

Cách 2: Trong Authorization

GET /shop/detail HTTP/1.1
Host: open.goihangchuan.vn
Authorization: Bearer YOUR_API_KEY

Cách 3: Trong query string - Không khuyến nghị

GET /shop/detail?api_key=YOUR_API_KEY

4. Ví dụ Request

Lấy danh sách đơn hàng

curl -X GET \
  'https://open.goihangchuan.vn/order/get/all?page=1&limit=10' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Lưu ý: Thay YOUR_API_KEY bằng API Key của bạn. Bạn nên tham khảo tài liệu OpenAPI để biết đầy đủ các field bắt buộc và mô tả chi tiết của các endpoint.

5. Webhook

Gói Hàng Chuẩn hỗ trợ Webhook cho sự kiện tạo đơn hàng mới.
URL webhook được thiết lập trong lúc đăng ký tài khoản đối tác.

5.1. Xác thực webhook

Mỗi payload được gửi kèm chữ ký (signature) trong header, sử dụng Webhook Secret để xác thực.

Header:x-hmac-signature: HMAC_SHA256_HEX_SIGNATURE
Xác thực ví dụ (Python):

import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = b'your_webhook_secret_here'

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    payload = request.get_data()  # raw body
    signature = request.headers.get("X-HMAC-Signature")

    if not signature:
        abort(400, "Missing signature header")

    # Tính chữ ký HMAC SHA256
    expected_signature = hmac.new(
        WEBHOOK_SECRET,
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected_signature, signature):
        abort(403, "Invalid signature")

    # Đã xác thực thành công
    data = request.json
    print("Webhook received:", data)
    return "OK", 200

if __name__ == "__main__":
    app.run(port=5000)

Header:x-hmac-signature: HMAC_SHA256_HEX_SIGNATURE
Xác thực ví dụ (Node.js):

const express = require("express");
const crypto = require("crypto");
const bodyParser = require("body-parser");

const app = express();
const WEBHOOK_SECRET = "your_webhook_secret_here";

app.use(bodyParser.raw({ type: "application/json" }));

app.post("/webhook", (req, res) => {
  const signature = req.headers["x-hmac-signature"];
  const payload = req.body;

  if (!signature) {
    return res.status(400).send("Missing signature header");
  }

  const expectedSignature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");

  if (signature !== expectedSignature) {
    return res.status(403).send("Invalid signature");
  }

  const data = JSON.parse(payload.toString());
  console.log("Webhook received:", data);
  res.send("OK");
});

app.listen(5000, () => {
  console.log("Server is listening on port 5000");
});

5.2. Retry

Webhook sẽ được gửi tối đa 3 lần nếu server không phản hồi thành công (HTTP status code khác 2xx).

6. Cập nhật thông tin đối tác

Hiện tại, để cập nhật thông tin tài khoản đối tác, bạn vui lòng liên hệ trực tiếp bộ phận CSKH của Gói Hàng Chuẩn qua các kênh hỗ trợ chính thức.

7. Gỡ quyền truy cập API

Khách hàng có thể tự gỡ quyền truy cập API đã cấp bằng cách truy cập đường dẫn sau:

🔗 https://goihangchuan.vn/xoaquyen

Chỉ cần nhập API Key muốn huỷ kích hoạt và xác nhận.

Nếu bạn cần thêm hỗ trợ kỹ thuật, vui lòng liên hệ đội ngũ hỗ trợ kỹ thuật của Gói Hàng Chuẩn tại: [email protected]