مستندات توسعه‌دهنده

شروع سریع

در سه مرحله احراز هویت بلینر را به سایت خود اضافه کنید:

1. ۱

   ثبت‌نام و ساخت اپ

   در داشبورد مرچنت ثبت‌نام کنید، یک اپ جدید بسازید و client_id و client_secret خود را دریافت کنید.

2. ۲

   انتخاب روش یکپارچه‌سازی

   می‌توانید از جریان OIDC استاندارد یا از API مستقیم لینک احراز استفاده کنید.

3. ۳

   دریافت اطلاعات کاربر

   پس از احراز هویت موفق، توکن حاوی اطلاعات هویتی کاربر (موبایل، کد ملی، سطح احراز) به سایت شما ارسال می‌شود.

API لینک احراز هویت مستقیم

ساده‌ترین روش: یک لینک شخصی‌سازی‌شده برای کاربر بسازید و او را به آنجا هدایت کنید. نیازی به پیاده‌سازی OIDC ندارید.

{
  "verify_url": "https://belener.ir/verify/uuid",
  "session_id": "uuid",
  "expires_at": "2024-01-01T12:30:00Z"
}

{
  "sub": "user-uuid",         // شناسه کاربر
  "level": 2,                 // سطح احراز
  "sessionId": "session-uuid",
  "iat": 1704067200,
  "exp": 1704067800           // ۱۰ دقیقه اعتبار
}

// API مستقیم: ساخت لینک احراز هویت اختصاصی
const res = await fetch('https://belener.ir/api/v1/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'cl_YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    redirect_url: 'https://yoursite.ir/kyc-callback',
    level: 2,  // سطح احراز موردنیاز: 1، 2، یا 3
  }),
});
const { verify_url, session_id, expires_at } = await res.json();

// کاربر را به verify_url هدایت کنید
// پس از احراز هویت، به redirect_url با ?result_token=... باز می‌گردد

// تأیید result_token در سرور
import { jwtVerify } from 'jose';
const secret = new TextEncoder().encode(process.env.AUTH_SECRET);
const { payload } = await jwtVerify(result_token, secret);
// payload: { sub: userId, level: 2, sessionId }

یکپارچه‌سازی OIDC استاندارد

اگر سیستم شما از OpenID Connect پشتیبانی می‌کند (مثل WordPress، Laravel، Django)، از Discovery URL استفاده کنید:

https://belener.ir/.well-known/openid-configuration

مرجع API

سطوح احراز هویت

هر سطح مشخص می‌کند چه scope‌هایی باید درخواست شوند و چه claims‌هایی در پاسخ برمی‌گردند. scope openid همیشه الزامی است و در همه سطوح وجود دارد.

کدهای نمونه — یکپارچه‌سازی OIDC

نمونه‌کد کامل برای فریم‌ورک‌ها و زبان‌های مختلف. همه از Discovery URL و استاندارد OIDC استفاده می‌کنند.

import { Issuer, generators } from 'openid-client';

const issuer = await Issuer.discover('https://belener.ir');
const client = new issuer.Client({
  client_id: 'cl_YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET',
  redirect_uris: ['https://yoursite.ir/callback'],
  response_types: ['code'],
});

// ۱. هدایت کاربر به صفحه احراز
const code_verifier = generators.codeVerifier();
const code_challenge = generators.codeChallenge(code_verifier);
const url = client.authorizationUrl({
  scope: 'openid profile mobile national_id verification_level',
  code_challenge,
  code_challenge_method: 'S256',
});
res.redirect(url);

// ۲. در callback: دریافت توکن
const params = client.callbackParams(req);
const tokenSet = await client.oauthCallback(
  'https://yoursite.ir/callback',
  params,
  { code_verifier }
);
const user = tokenSet.claims(); // { sub, phone_number, name, verification_level }

نکات امنیتی

• ⚠هرگز client_secret را در کد فرانت‌اند، مخزن عمومی یا لاگ‌ها قرار ندهید.
• ⚠ارتباط با API فقط از HTTPS با TLS 1.2+ باشد.
• ⚠client_secret را هر ۹۰ روز یا پس از هر رویداد امنیتی تغییر دهید.
• ⚠پارامتر state را در جریان OIDC برای جلوگیری از CSRF تأیید کنید.
• ⚠IP سرورهایی که با client_secret تماس می‌گیرند را در فایروال محدود کنید.
• ⚠result_token را در سرور تأیید کنید — هرگز در کلاینت به آن اعتماد نکنید.
• ⚠برای احراز سطح ۳ (ویدیویی)، مطمئن شوید محتوای ویدیو ارسال‌شده مطابق دستورالعمل است.