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)
- Đă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). - Gọi thử:
curl https://trywigo.com/v1/ping \
-H "Authorization: Bearer wgk_test_xxxxxxxx"
- 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ùng | Như 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ức | Tối đa 50 người dùng | Theo 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ế).
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ầu | Mô tả |
|---|---|
GET /v1/users/{external_id}/sites | Danh sách site của người dùng |
POST /v1/users/{external_id}/sites | Tạ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ện | Khi nào |
|---|---|
user.created · user.removed | Tạo / xoá người dùng qua API |
user.entitlement_changed | Quyề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.deleted | Người dùng tạo / đăng / xoá site |
webhook.test | Bạ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":"…"}:
| HTTP | error | Ý nghĩa |
|---|---|---|
| 400 | bad_request, bad_url, bad_redirect | Dữ liệu không hợp lệ |
| 401 | missing, invalid | Thiếu/sai/đã thu hồi khoá |
| 403 | suspended, not_live | Đối tác bị tạm khoá / khoá production chưa kích hoạt |
| 404 | not_found | Không có người dùng/site (hoặc thuộc đối tác khác) |
| 409 | email_in_use, seat_limit, user_limit, site_limit, no_webhook | Xung đột/hết hạn mức |
| 429 | — | Quá 120 yêu cầu/phút/khoá |
Nhật ký thay đổi
- v1 (2026-10-30): ra mắt — người dùng, SSO login-link, site + đăng site, webhook ký HMAC, sandbox/production, ghế theo năm.
Cần hỗ trợ tích hợp: [email protected].