将 Wigo 集成到您的产品中
让您的会员直接在您自己的系统内创建网站:创建用户、通过单点登录让其登录、创建/发布网站,并在发生变化时接收 webhook。下载 OpenAPI 3 规范即可生成客户端。
快速开始(5 分钟)
- 注册成为合作伙伴(需要已验证的邮箱)— 您将立即进入沙盒并获得
wgk_test_…密钥(仅显示一次,请妥善保存)。 - 试调用一次:
curl https://trywigo.com/v1/ping \
-H "Authorization: Bearer wgk_test_xxxxxxxx"
- 创建用户、获取登录链接,并将用户带入 Wigo:
# 1) create/update a member (idempotent by 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) ONE-TIME login link (expires in 60 seconds)
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} — redirect the user's browser to this url
身份验证
请在每个 /v1/* 请求中带上请求头 Authorization: Bearer <key>,请求须由您的服务器发出(切勿把密钥放进在浏览器中运行的代码里)。Wigo 只存储密钥的哈希;如果丢失密钥,请在合作伙伴门户中吊销并重新创建(每种模式最多 5 个密钥)。速率限制:每个密钥每分钟 120 次请求。
沙盒与生产环境
Sandbox (wgk_test_…) | Production (wgk_live_…) | |
|---|---|---|
| 获取方式 | 自助注册,立即使用 | 填写法人信息 → 申请生产环境 → Wigo 管理员审批 → 购买席位套餐 |
| 用户权益 | 与免费试用套餐相同(1 个网站、无 AI、带徽标 + noindex、自动清理) | 与对应的个人套餐(Basic/Professional)相同;用户不会看到付款提醒 |
| 配额 | 最多 50 个用户 | 取决于所购席位数量 |
两种模式完全独立:测试密钥看不到生产用户,反之亦然。
用户
PUT/v1/users/{external_id} — 创建或更新。请求体:email(创建时必填)、name、plan(basic|pro,仅限生产环境;默认使用可用的 Professional 席位)。创建时返回 201,用户已存在时返回 200。
GET/v1/users/{external_id} · DELETE/v1/users/{external_id}(将用户从合作伙伴中移除:释放席位、权益到期,网站进入 15/30/45 天的到期生命周期)· GET/v1/usage(用户数和席位数)。
email_in_use)— 合作伙伴无法接管他人的账号。通过 API 新创建的用户首次访问时必须接受 Wigo 服务条款。单点登录(SSO)
POST/v1/users/{external_id}/login-links — 返回 {"url", "expires_in":60}。将用户重定向到 url:Wigo 会用该链接换取登录会话,然后跳转到 redirect(格式为 /#/path,默认 /#/my-site)。该链接仅可使用一次,60 秒后过期;重复使用/已过期的链接 ⇒ 显示友好的提示页。合作伙伴身份验证即您的 API 密钥本身。
网站与发布
| 请求 | 说明 |
|---|---|
GET /v1/users/{external_id}/sites | 列出该用户的网站 |
POST /v1/users/{external_id}/sites | 创建网站:{"name":"Quán A","template":"quan-ca-phe"}(template 可选)。达到套餐上限 ⇒ 409 site_limit |
POST /v1/sites/{id}/deploy | 发布网站:{"subdomain":"quan-a"} ⇒ 202 {"job_id","version"};网站将运行在 https://quan-a.trywigo.com,并且您会收到 site.deployed webhook |
Webhooks
设置一个 HTTPS 地址,可在合作伙伴门户中设置,或通过 PUT /v1/webhook {"url":"https://…"} 设置(会返回签名密钥 whsec_…);POST /v1/webhook/test 会发送一个测试事件。指向内网的地址会被拒绝。Wigo 会发送 JSON 格式的 POST:
{ "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 } } }
| 事件 | 触发时机 |
|---|---|
user.created · user.removed | 通过 API 创建/移除用户 |
user.entitlement_changed | 权益开始/停止生效(续费、席位用尽、合作伙伴退回沙盒) |
site.created · site.deployed · site.deleted | 用户创建/发布/删除网站 |
webhook.test | 您点击“发送测试” |
验证签名
请求头 X-Wigo-Signature: t=<unix>,v1=<hex>,其中 v1 = HMAC-SHA256(secret, "<t>." + <raw body>)。请针对原始请求体验证签名,如果 t 与当前时间相差超过 5 分钟则拒绝该请求。
// 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);
}
投递:请在 10 秒内返回 2xx 状态码以确认接收。失败后将依次在 1 分钟 → 5 分钟 → 30 分钟 → 2 小时 → 12 小时后重试(含首次共最多 6 次);可在合作伙伴门户查看日志并点击“重新发送”。事件可能重复或乱序到达 — 请按 id 做幂等处理。
席位与权益(生产环境)
每个生产环境用户占用 1 个席位,并获得与对应个人套餐相同的权益。请在合作伙伴门户按年购买席位(最少 100 个席位,阶梯折扣)。席位用尽 ⇒ 409 seat_limit。席位到期或合作伙伴退回沙盒 ⇒ 用户会收到 user.entitlement_changed webhook(active:false)并进入到期生命周期(15 天后仅可查看,30 天后网站被暂停,45 天后被清理)— 用户可自行购买个人套餐以保留网站。
错误与限制
错误以 JSON 形式返回 {"error":"code","message":"…"}:
| HTTP | error | 含义 |
|---|---|---|
| 400 | bad_request, bad_url, bad_redirect | 数据无效 |
| 401 | missing, invalid | 密钥缺失/错误/已吊销 |
| 403 | suspended, not_live | 合作伙伴已被暂停 / 生产密钥尚未激活 |
| 404 | not_found | 未找到用户/网站(或属于其他合作伙伴) |
| 409 | email_in_use, seat_limit, user_limit, site_limit, no_webhook | 冲突 / 超出配额 |
| 429 | — | 每个密钥每分钟超过 120 次请求 |
更新日志
- v1(2026-10-30):发布 — 用户、SSO 登录链接、网站 + 发布、HMAC 签名的 webhook、沙盒/生产环境、按年席位。
需要集成支持: [email protected].