API و وبهوک‌های یوزر تستینگ

احراز هویت

کلید را در هدر Authorization بفرستید. کلید تنها یک بار، هنگام ساخت، نمایش داده می‌شود؛ هر درخواست به نام مالک فضای کاری و در محدوده همان فضا اجرا می‌شود.

curl https://api.usertesting.ir/api/public/v1/me \
  -H "Authorization: Bearer ut_live_xxxxxxxxxxxxxxxxxxxxxxxx"

• دامنه read برای خواندن، write برای عملیات تغییردهنده.
• سقف نرخ: ۶۰۰ درخواست در دقیقه به ازای هر کلید (هدرهای RateLimit-* برمی‌گردند).
• هر پاسخ یک X-Request-Id دارد؛ هنگام گزارش مشکل آن را ذکر کنید.

نقاط پایانی

آدرس پایه: https://api.usertesting.ir/api/public/v1

پاسخ‌ها به شکل { "message": "...", "data": { ... } } هستند؛ فهرست‌ها items، page، limit و total دارند. حداکثر limit برابر ۲۰۰ است.

{
  "message": "انجام شد.",
  "data": {
    "items": [
      { "id": "665…", "name": "دسته‌بندی منوی فروشگاه", "type": "cart-sorting-test",
        "status": "published", "responses": 53, "completion_rate": 81, "created_at": "2026-09-01T10:12:00.000Z" }
    ],
    "page": 1, "limit": 50, "total": 1
  }
}

وبهوک‌ها

برای هر رویداد یک درخواست POST با بدنه JSON به آدرس شما فرستاده می‌شود. آدرس باید https باشد و با کد ۲xx پاسخ دهد؛ در غیر این صورت تا ۵ بار با فاصله افزایشی (۱، ۵، ۳۰ و ۱۲۰ دقیقه) تکرار می‌شود. بعد از ۲۵ شکست پیاپی وبهوک خودکار غیرفعال می‌شود.

هدرها و امضا

هر ارسال هدرهای X-UT-Event، X-UT-Delivery، X-UT-Timestamp و X-UT-Signature دارد. امضا، HMAC-SHA256 رشته {timestamp}.{body} با کلید محرمانه وبهوک است. برای جلوگیری از حمله تکرار، ارسال‌های قدیمی‌تر از ۵ دقیقه را رد کنید.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(req, secret) {
  const ts = req.headers["x-ut-timestamp"];
  const sig = req.headers["x-ut-signature"];              // "sha256=…"
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(`${ts}.${req.rawBody}`).digest("hex");
  return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

{
  "id": "0f3c…", "event": "response.created", "created_at": "2026-09-26T09:30:00.000Z",
  "workspace": "665…",
  "data": { "test_id": "665…", "test_name": "دسته‌بندی منوی فروشگاه", "test_type": "cart-sorting-test" }
}

MCP برای دستیارهای هوش مصنوعی

همان داده، از راه Model Context Protocol (Streamable HTTP، بدون وضعیت). با همان کلید API، فقط‌خواندنی. نقطه پایانی https://api.usertesting.ir/mcp با هدر Authorization: Bearer، یا برای کلاینت‌هایی که هدر نمی‌فرستند https://api.usertesting.ir/mcp/k/<key>. سقف ۳۰۰ درخواست در دقیقه به ازای هر کلید.

claude mcp add --transport http usertesting https://api.usertesting.ir/mcp \
  --header "Authorization: Bearer ut_live_..."

راهنمای گام‌به‌گام اتصال در Claude Desktop، claude.ai و Claude Code در پایگاه دانش آمده است.

خطاها

• 401 کلید نامعتبر یا باطل‌شده · 402 پلن فضای کاری API را شامل نمی‌شود · 403 دامنه کلید کافی نیست یا منبع متعلق به این فضا نیست
• 404 منبع پیدا نشد · 429 سقف نرخ · 5xx خطای سرور (با request_id در بدنه)