راهنمای جامع توسعه‌دهندگان ویوان (vo1.ir): API key، scopeها و وبهوک‌ها

می‌خواهید ویوان (vo1.ir) را به CRM، سیستم گزارش‌گیری، ابزار اتوماسیون، پنل داخلی یا سرویس backend خود متصل کنید؟ در این راهنما، مسیر کامل setup یک integration امن را قدم‌به‌قدم مرور می‌کنیم — از ساخت اولین API key تا اعتبارسنجی امضای وبهوک. اگر تا به حال با API کار نکرده‌اید، نگران نباشید: هر مرحله با مثال عملی توضیح داده شده است.

نکته مهم امنیتی: secretها فقط یک‌بار در زمان ایجاد نمایش داده می‌شوند. آن‌ها را در frontend، مخزن کد، فایل‌های عمومی یا لاگ‌های بدون محافظت ذخیره نکنید.

معماری integration در ویوان چگونه است؟

هر integration در ویوان روی سه پایه اصلی بنا شده است:

1. API key برای احراز هویت درخواست‌های ماشین‌به‌ماشین
2. Scope برای محدود کردن دسترسی هر کلید
3. Webhook برای دریافت رویدادها به‌صورت push از سمت ویوان

این طراحی باعث می‌شود هم دسترسی‌ها دقیق‌تر کنترل شوند و هم نیاز به polling مداوم برای بسیاری از workflowها از بین برود.

۱) ساخت API key

اولین قدم، ساخت یک کلید API است. از مسیرهای زیر وارد شوید:

• مدیریت API key
• مدیریت وبهوک‌ها

در زمان ساخت کلید:

• یک نام واضح انتخاب کنید؛ مثل CI Deploy, Reporting Bot, CRM Sync
• فقط scopeهای ضروری را فعال کنید
• secret را همان لحظه در vault یا secret manager ذخیره کنید
• اگر کلید دیگر لازم نیست یا احتمال نشت دارد، فوراً آن را revoke کنید

بهترین شیوه نام‌گذاری کلیدها

نام کلید باید سه چیز را روشن کند: کاربرد، محیط، و مالک. این کار در آینده مدیریت کلیدها را بسیار آسان‌تر می‌کند.

۲) احراز هویت درخواست‌ها

ویوان برای درخواست‌های غیرمرورگری از دو الگوی header پشتیبانی می‌کند. انتخاب بین این دو بستگی به نوع integration شما دارد:

Authorization: Bearer

روش استاندارد و رایج. مناسب برای اکثر زبان‌ها و فریم‌ورکها:

curl -X GET "https://vo1.ir/api/v1/links/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

X-API-Key

اگر integration شما از middlewareها یا gatewayهایی استفاده می‌کند که header استاندارد Authorization را تغییر می‌دهند، این روش ساده‌تر است:

curl -X GET "https://vo1.ir/api/v1/analytics/overview/" \
  -H "X-API-Key: YOUR_API_KEY"

چه زمانی از JWT استفاده می‌شود؟

JWT همچنان برای جریان‌های dashboard و session-based frontend حفظ شده است. اما برای botها، jobها، CI/CD و backend integration حتماً از API key استفاده کنید تا دسترسی ماشین‌به‌ماشین از session کاربر جدا بماند.

۳) scopeها و اصل حداقل دسترسی

هر API key باید فقط به scopeهایی دسترسی داشته باشد که واقعاً نیاز دارد. این کار سطح ریسک را کم می‌کند و در صورت نشت یک کلید، دامنه آسیب را محدود نگه می‌دارد.

scopeهای موجود

چند الگوی پیشنهادی

ربات گزارش‌گیری — برای خواندن داده و ساخت dashboard داخلی: analytics:read + links:read

سرویس ساخت لینک خودکار — برای ایجاد یا ویرایش لینک‌ها: links:write + links:read

ابزار مدیریت دامنه — برای نمایش و مدیریت دامنه‌های اختصاصی: domains:read + domains:write

اسکریپت هماهنگ‌سازی namespaceها: namespaces:read + namespaces:write

چه زمانی 403 می‌گیرید؟

اگر کلید از نظر احراز هویت معتبر باشد اما scope مناسب را نداشته باشد، endpoint با 403 پاسخ می‌دهد. این رفتار طبیعی است و نشانه‌ی مشکل در انتخاب scope است، نه در خود کلید. کافی است scopeهای لازم را به کلید اضافه کنید.

۴) مسیرهای اصلی API عمومی

برای بیشتر integrationها این endpointها کافی هستند:

GET    /api/v1/links/
POST   /api/v1/links/
GET    /api/v1/links/:id/
PATCH  /api/v1/links/:id/
GET    /api/v1/links/:id/analytics/
GET    /api/v1/analytics/overview/

چند مثال کاربردی

گرفتن لیست لینک‌ها

curl -X GET "https://vo1.ir/api/v1/links/?page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

ساخت لینک جدید

curl -X POST "https://vo1.ir/api/v1/links/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com/campaign",
    "title": "Spring Campaign"
  }'

گرفتن تحلیل یک لینک

curl -X GET "https://vo1.ir/api/v1/links/42/analytics/?range=30d" \
  -H "X-API-Key: YOUR_API_KEY"

فیلترهای تحلیل

برای endpointهای تحلیلی می‌توانید از بازه‌های از پیش تعریف‌شده یا بازه سفارشی استفاده کنید:

• range=7d — هفت روز اخیر
• range=30d — سی روز اخیر
• range=90d — نود روز اخیر
• range=365d — یک سال اخیر
• start_date=2026-05-01&end_date=2026-05-24 — بازه دلخواه

دقت کنید که بعضی قابلیت‌های تحلیلی با پلن کاربر کنترل می‌شوند. اگر فیلدی در پلن شما فعال نباشد، API همان محدودیت dashboard را حفظ می‌کند.

۵) وبهوک‌ها چه مشکلی را حل می‌کنند؟

فرض کنید می‌خواهید هر بار که لینک جدیدی ساخته می‌شود، آن را در CRM ثبت کنید. روش قدیمی: هر ۵ دقیقه API را چک کنید و ببینید آیا لینک جدیدی اضافه شده. روش هوشمندانه: وبهوک. به‌جای اینکه شما دنبال رویدادها بگردید، ویوان خودش رویداد را به endpoint شما ارسال می‌کند.

رویدادهای فعلی

نمونه موارد استفاده

• CRM: ثبت لینک‌های تازه به‌صورت خودکار
• Slack: اطلاع‌رسانی تیمی بعد از تایید دامنه
• Billing: بروزرسانی subscription state در سیستم داخلی
• Data pipeline: trigger کردن workflowهای downstream بعد از ایجاد یا تغییر لینک

۶) ساخت و مدیریت endpoint وبهوک

از مسیر مدیریت وبهوک‌ها می‌توانید:

• endpoint جدید بسازید
• event subscriptionها را انتخاب کنید
• endpoint را غیرفعال یا فعال کنید
• تاریخچه ارسال‌های اخیر را ببینید

توصیه‌های عملی برای endpoint وبهوک

• endpoint باید HTTPS و قابل‌اعتماد باشد
• پاسخ 2xx را سریع برگردانید و پردازش سنگین را async انجام دهید
• رویدادها را idempotent پردازش کنید (پردازش تکراری نباید مشکلی ایجاد کند)
• از X-Vo1-Delivery برای deduplication و logging استفاده کنید

۷) اعتبارسنجی امضای وبهوک

هر payload وبهوک با HMAC-SHA256 امضا می‌شود. این امضا تضمین می‌کند که پیام واقعاً از سمت ویوان ارسال شده و در مسیر تغییر نکرده است. بررسی امضا یک مرحله امنیتی حیاتی است که نباید نادیده گرفته شود.

headerهای مهم

نمونه اعتبارسنجی در Node.js

const crypto = require('crypto');

function verifyVo1Signature(rawBody, secret, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader || '')
  );
}

چرا raw body مهم است؟

امضا روی raw request body محاسبه می‌شود. اگر قبل از اعتبارسنجی body را parse و دوباره serialize کنید، ممکن است ترتیب فیلدها یا formatting تغییر کند و signature mismatch بگیرید. پس در middleware خود raw body را نگه دارید و فقط بعد از اعتبارسنجی آن را parse کنید.

اگر اعتبارسنجی شکست خورد چه کنیم؟

• درخواست را با 401 یا 403 رد کنید
• event و delivery id را log کنید تا بعداً قابل پیگیری باشد
• secret را دوباره بررسی کنید
• مطمئن شوید payload روی raw body اعتبارسنجی می‌شود، نه روی object parse‌شده

۸) الگوی پیشنهادی برای receiver وبهوک

یک receiver خوب معمولاً این مراحل را انجام می‌دهد:

1. دریافت raw body — body را قبل از هر پردازشی نگه دارید
2. بررسی X-Vo1-Signature — امضای HMAC را با timingSafeEqual مقایسه کنید
3. ثبت X-Vo1-Delivery — شناسه تحویل را برای idempotency ذخیره کنید
4. Parse کردن payload — فقط بعد از موفقیت امضا، payload را پردازش کنید
5. Enqueue کردن job داخلی — پردازش سنگین را به background job بسپارید
6. بازگرداندن پاسخ 2xx — سریع‌ترین پاسخ ممکن را برگردانید

anti-patternهای رایج

۹) پیشنهاد setup برای تیم‌ها

تیم بازاریابی

• یک API key فقط برای analytics و خواندن لینک‌ها
• یک webhook برای link.created و link.updated
• sink کردن داده‌ها به Google Sheets، BI یا Slack

تیم backend

• کلیدهای جداگانه برای staging و production
• secret manager برای نگه‌داری کلیدها و webhook secretها
• logging ساخت‌یافته با X-Vo1-Delivery

تیم data

• استفاده از webhook برای ingest سریع eventها
• استفاده از API عمومی برای backfill و reconciliation
• نگه‌داری delivery id برای جلوگیری از duplicate ingestion

۱۰) از کجا شروع کنم؟

اگر می‌خواهید سریع شروع کنید، این ترتیب پیشنهاد می‌شود:

1. از مدیریت API key یک کلید بسازید — ۱ دقیقه
2. برای کلید فقط scopeهای لازم را انتخاب کنید — ۳۰ ثانیه
3. با یک درخواست ساده GET /api/v1/links/ احراز هویت را تست کنید — ۱ دقیقه
4. یک endpoint وبهوک در مدیریت وبهوک‌ها ثبت کنید — ۱ دقیقه
5. اعتبارسنجی X-Vo1-Signature را پیاده‌سازی کنید — ۲ دقیقه
6. workflow اصلی خود را به رویدادها متصل کنید

زمان کل تا اولین درخواست موفق: کمتر از ۵ دقیقه.

اگر integration شما هنوز در مرحله discovery است، با یک کلید فقط-خواندنی و یک endpoint webhook برای link.created شروع کنید. این کم‌ریسک‌ترین نقطه ورود است.

جمع‌بندی

ویوان برای integrationهای واقعی طراحی شده است: API keyهای یک‌بارنمایش، scopeهای صریح، API عمومی versioned و وبهوک‌های امضاشده. اگر از همان ابتدا اصل حداقل دسترسی، ذخیره امن secret و idempotency در receiver را رعایت کنید، می‌توانید بدون پیچیدگی اضافه یک integration پایدار و production-ready بسازید.

آماده شروع هستید؟

• مدیریت API key — کلید خود را بسازید
• مدیریت وبهوک‌ها — endpoint ثبت کنید
• صفحه قیمت‌گذاری — پلن مناسب خود را انتخاب کنید

مقالات مرتبط

• راهنمای جامع پلن‌های ویوان: نشانی شما در هر مقیاس — Starter، Pro و Business
• تحلیل ویوان: راهنمای کامل قابلیت‌های تحلیلی به تفکیک پلن
• نشانی شما در وب: صفحه‌ی عمومی، بخشی جدایی‌ناپذیر از ویوان
• بهینه‌سازی SEO و مدیریت لینک‌ها: راهنمای جامع برای موفقیت آنلاین