Tích hợp Wigo vào sản phẩm của bạn

Tạo website cho thành viên của bạn ngay trong hệ thống của bạn: tạo người dùng, đăng nhập một lần, tạo/đăng site và nhận webhook khi có thay đổi. Tải OpenAPI 3 để sinh client.

Bắt đầu nhanh (5 phút)

  1. Đăng ký đối tác (cần email đã xác minh) — bạn vào ngay sandbox và nhận một khoá wgk_test_… (chỉ hiện một lần, hãy lưu lại).
  2. Gọi thử:
curl https://trywigo.com/v1/ping \
  -H "Authorization: Bearer wgk_test_xxxxxxxx"
  1. Tạo người dùng, lấy liên kết đăng nhập và đưa người dùng vào Wigo:
# 1) tạo/cập nhật thành viên (idempotent theo external_id)
curl -X PUT https://trywigo.com/v1/users/member-123 \
  -H "Authorization: Bearer $WIGO_KEY" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Nguyễn Văn A"}'

# 2) liên kết đăng nhập MỘT LẦN (hạn 60 giây)
curl -X POST https://trywigo.com/v1/users/member-123/login-links \
  -H "Authorization: Bearer $WIGO_KEY" -H "Content-Type: application/json" \
  -d '{"redirect":"/#/my-site"}'
# → {"url":"https://trywigo.com/sso/…","expires_in":60}  — chuyển hướng trình duyệt của người dùng tới url này

Xác thực

Mọi yêu cầu /v1/* gửi header Authorization: Bearer <khoá> từ máy chủ của bạn (không bao giờ đặt khoá trong mã chạy trên trình duyệt). Khoá lưu băm ở Wigo; mất khoá thì thu hồi và tạo khoá mới trong cổng đối tác (tối đa 5 khoá mỗi chế độ). Giới hạn 120 yêu cầu/phút/khoá.

Sandbox và Production

Sandbox (wgk_test_…)Production (wgk_live_…)
Cách cóTự đăng ký, dùng ngayĐiền thông tin pháp nhân → xin lên production → admin Wigo duyệt → mua gói ghế
Quyền lợi người dùngNhư gói dùng thử miễn phí (1 site, không AI, huy hiệu + noindex, tự dọn)Như gói cá nhân cùng loại (Cơ bản/Chuyên nghiệp), người dùng không thấy lời nhắc thanh toán
Hạn mứcTối đa 50 người dùngTheo số ghế đã mua

Hai chế độ tách biệt hoàn toàn: khoá test không thấy người dùng live và ngược lại.

Người dùng

PUT/v1/users/{external_id} — tạo hoặc cập nhật. Body: email (bắt buộc khi tạo), name, plan (basic|pro, chỉ production; mặc định ghế Chuyên nghiệp còn trống). Trả 201 khi tạo, 200 khi đã có.

GET/v1/users/{external_id} · DELETE/v1/users/{external_id} (xoá khỏi đối tác: trả ghế, quyền lợi hết hạn, site vào vòng đời quá hạn 15/30/45 ngày) · GET/v1/usage (số người dùng và ghế).

An toàn tài khoản: email đã có tài khoản Wigo độc lập sẽ bị từ chối (email_in_use) — đối tác không thể chiếm tài khoản của người khác. Người dùng mới tạo qua API phải đồng ý Điều khoản của Wigo ở lần vào đầu tiên.

Đăng nhập một lần (SSO)

POST/v1/users/{external_id}/login-links — trả {"url", "expires_in":60}. Chuyển hướng người dùng tới url: Wigo đổi liên kết lấy phiên đăng nhập rồi đưa tới redirect (dạng /#/đường-dẫn, mặc định /#/my-site). Liên kết dùng một lần, hạn 60 giây; dùng lại/hết hạn ⇒ trang thông báo thân thiện. Việc xác minh đối tác chính là khoá API của bạn.

Site và đăng site

Yêu cầuMô tả
GET /v1/users/{external_id}/sitesDanh sách site của người dùng
POST /v1/users/{external_id}/sitesTạo site: {"name":"Quán A","template":"quan-ca-phe"} (mẫu tuỳ chọn). Chạm giới hạn gói ⇒ 409 site_limit
POST /v1/sites/{id}/deployĐăng site: {"subdomain":"quan-a"} ⇒ 202 {"job_id","version"}; site chạy tại https://quan-a.trywigo.com và bạn nhận webhook site.deployed

Webhook

Đặt địa chỉ HTTPS trong cổng đối tác hoặc PUT /v1/webhook {"url":"https://…"} (lấy khoá ký whsec_…); POST /v1/webhook/test gửi sự kiện thử. Địa chỉ trỏ vào mạng nội bộ bị từ chối. Wigo gửi POST JSON:

{ "id": "evt-uuid", "type": "site.deployed", "created": "2026-10-30T03:00:00Z", "livemode": false,
  "data": { "user": { "external_id": "member-123", "email": "[email protected]" },
            "site": { "id": "…", "name": "Quán A", "subdomain": "quan-a", "url": "https://quan-a.trywigo.com", "version": 1 } } }
Sự kiệnKhi nào
user.created · user.removedTạo / xoá người dùng qua API
user.entitlement_changedQuyền lợi bắt đầu/hết hiệu lực (gia hạn, hết ghế, đối tác bị trả về sandbox)
site.created · site.deployed · site.deletedNgười dùng tạo / đăng / xoá site
webhook.testBạn bấm "Gửi thử"

Kiểm tra chữ ký

Header X-Wigo-Signature: t=<unix>,v1=<hex> với v1 = HMAC-SHA256(secret, "<t>." + <body thô>). Hãy kiểm tra chữ ký trên body thô và từ chối nếu t lệch quá 5 phút.

// Node.js
const crypto = require("crypto");
function verify(rawBody, header, secret) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}
# Python
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    t, v1 = [p.split("=", 1)[1] for p in header.split(",")]
    if abs(time.time() - int(t)) > 300: return False
    mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, v1)
<?php // PHP
function verify(string $raw, string $header, string $secret): bool {
  [$t, $v1] = array_map(fn($p) => explode("=", $p, 2)[1], explode(",", $header));
  if (abs(time() - (int)$t) > 300) return false;
  return hash_equals(hash_hmac("sha256", "$t.$raw", $secret), $v1);
}

Giao nhận: trả mã 2xx trong 10 giây là đã nhận. Thất bại được thử lại sau 1 phút → 5 phút → 30 phút → 2 giờ → 12 giờ (tối đa 6 lần gồm lần đầu); xem nhật ký và bấm "Gửi lại" trong cổng đối tác. Sự kiện có thể đến trùng hoặc sai thứ tự — hãy xử lý idempotent theo id.

Ghế và quyền lợi (production)

Mỗi người dùng production chiếm 1 ghế và nhận quyền lợi như gói cá nhân cùng loại. Mua ghế theo năm (tối thiểu 100 ghế, giá giảm theo bậc) trong cổng đối tác. Hết ghế ⇒ 409 seat_limit. Ghế hết hạn hoặc đối tác bị trả về sandbox ⇒ người dùng nhận webhook user.entitlement_changed (active:false) và rơi vào vòng đời quá hạn (chỉ xem sau 15 ngày, site tạm ngưng sau 30 ngày, dọn sau 45 ngày) — họ có thể tự mua gói cá nhân để giữ site.

Lỗi và giới hạn

Lỗi trả JSON {"error":"mã","message":"…"}:

HTTPerrorÝ nghĩa
400bad_request, bad_url, bad_redirectDữ liệu không hợp lệ
401missing, invalidThiếu/sai/đã thu hồi khoá
403suspended, not_liveĐối tác bị tạm khoá / khoá production chưa kích hoạt
404not_foundKhông có người dùng/site (hoặc thuộc đối tác khác)
409email_in_use, seat_limit, user_limit, site_limit, no_webhookXung đột/hết hạn mức
429—Quá 120 yêu cầu/phút/khoá

Nhật ký thay đổi

Cần hỗ trợ tích hợp: [email protected].