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

شروع سریع

چک‌لیست اتصال بلینر به سایت یا اپ شما:

1. ۱

   ثبت‌نام کسب‌وکار

   به /dashboard/register بروید، حساب بسازید و وارد داشبورد شوید.

2. ۲

   ساخت اپ و دریافت کلیدها

   از بخش «اپ‌ها» یک اپ جدید بسازید. دامنهٔ مجاز (مثلاً belener.ir) و redirect URIهای روی همان دامنه را ثبت کنید و client_id و client_secret را یک‌بار کپی کنید (secret فقط همان لحظه نمایش داده می‌شود).

3. ۳

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

   API لینک احراز (ساده‌تر) یا OIDC استاندارد. هر دو در همین صفحه توضیح داده شده‌اند.

4. ۴

   تأیید نتیجه در سرور

   پس از بازگشت کاربر result_token یا code را در سرور تأیید کنید. اگر کاربر مرورگر را بست، با session_id وضعیت را از POST /api/v1/verify-status پول کنید.

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

ساده‌ترین روش: یک لینک شخصی‌سازی‌شده برای کاربر بسازید و او را به آنجا هدایت کنید. نیازی به پیاده‌سازی OIDC ندارید. نتیجه را هم از بازگشت مرورگر (result_token) و هم با پول session_id می‌توانید بگیرید — حتی اگر کاربر مرورگر را بسته باشد.

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

{
  "sub": "user-uuid",
  "level": 2,
  "session_id": "session-uuid",
  "client_id": "cl_YOUR_CLIENT_ID",
  "user": {
    "phone_number": "09123456789",
    "name": "علی رضایی",
    "national_id": "0012345678",
    "card_number": "6037990000000006",
    "card_numbers": [
      "6037990000000006",
      "6219861012345678"
    ],
    "verification_level": 2
  },
  "billing": {
    "type": "verify",
    "charged": 20000
  }
}

// ۱) ساخت لینک احراز هویت
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://belener.ir/kyc-callback',
    level: 2,  // سطح احراز موردنیاز: 1، 2، یا 3
    mobile: '09123456789',  // شماره موبایل احرازشده توسط شما
  }),
});
const { verify_url, session_id, expires_at } = await res.json();

// کاربر را به verify_url هدایت کنید
// پس از احراز، به redirect_url با ?result_token=... بازمی‌گردد
// session_id را در سرور خود ذخیره کنید — اگر کاربر مرورگر را بست، با آن وضعیت را پول کنید

// ۲الف) تأیید result_token در سرور (هرگز در مرورگر) — بعد از بازگشت کاربر
const verify = await fetch('https://belener.ir/api/v1/verify-result', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'cl_YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    result_token: req.query.result_token,
  }),
});
const data = await verify.json();
// data: { sub, level, session_id, client_id, user: { phone_number, name, national_id, card_number, card_numbers, verification_level } }

// ۲ب) پول وضعیت با session_id (حتی اگر کاربر مرورگر را بسته باشد)
const poll = await fetch('https://belener.ir/api/v1/verify-status', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'cl_YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    session_id,
  }),
});
const status = await poll.json();
// status.status: pending | awaiting_review | needs_fix | completed | failed
// اگر completed باشد همان فیلدهای user را دارد — دیگر به بازگشت مرورگر وابسته نیستید

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

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

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

مرجع API

کدهای خطا

پاسخ‌های خطا به‌صورت JSON با فیلدهای error و error_description برمی‌گردند.

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

هر سطح مشخص می‌کند چه 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://belener.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 card_number verification_level',
  code_challenge,
  code_challenge_method: 'S256',
});
res.redirect(url);

// ۲. در callback: دریافت توکن
const params = client.callbackParams(req);
const tokenSet = await client.oauthCallback(
  'https://belener.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 را فقط با POST /api/v1/verify-result در سرور تأیید کنید — هرگز در کلاینت به آن اعتماد نکنید.
• ⚠session_id را در سرور ذخیره کنید و با POST /api/v1/verify-status وضعیت را پول کنید تا اگر کاربر مرورگر را بست نتیجه از دست نرود.
• ⚠برای احراز سطح ۳ (ویدیویی)، مطمئن شوید محتوای ویدیو ارسال‌شده مطابق دستورالعمل است.