将 Wigo 集成到您的产品中

让您的会员直接在您自己的系统内创建网站:创建用户、通过单点登录让其登录、创建/发布网站,并在发生变化时接收 webhook。下载 OpenAPI 3 规范即可生成客户端。

快速开始(5 分钟)

  1. 注册成为合作伙伴(需要已验证的邮箱)— 您将立即进入沙盒并获得 wgk_test_… 密钥(仅显示一次,请妥善保存)。
  2. 试调用一次:
curl https://trywigo.com/v1/ping \
  -H "Authorization: Bearer wgk_test_xxxxxxxx"
  1. 创建用户、获取登录链接,并将用户带入 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(用户数和席位数)。

账号安全:已拥有独立 Wigo 账号的邮箱会被拒绝(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":"…"}:

HTTPerror含义
400bad_request, bad_url, bad_redirect数据无效
401missing, invalid密钥缺失/错误/已吊销
403suspended, not_live合作伙伴已被暂停 / 生产密钥尚未激活
404not_found未找到用户/网站(或属于其他合作伙伴)
409email_in_use, seat_limit, user_limit, site_limit, no_webhook冲突 / 超出配额
429—每个密钥每分钟超过 120 次请求

更新日志

需要集成支持: [email protected].