API نسخهٔ ۱

مستندات فنی

ساخت فاکتور، استعلام وضعیت و دریافت وب‌هوک امضاشده. مبالغ پیش‌فرض به ریال است (با currency: "IRT" تومان).

شروع سریع

  1. در پنل ثبت‌نام کنید و کارت بانکی خود را در بخش «روش‌های پرداخت» اضافه کنید.
  2. اپ را روی گوشی‌ای که پیامک بانک را می‌گیرد نصب و با کد QR وصل کنید.
  3. کلید API را از پنل بردارید و با آن فاکتور بسازید.
  4. مشتری را به payment_url بفرستید و بعد از وب‌هوک «پرداخت موفق» سفارش را تحویل دهید.

احراز هویت

کلید API را در هدر x-api-key (یا Authorization: Bearer <key>) بفرستید. کلید را فقط سمت سرور نگه دارید و در کد مرورگر یا اپ قرار ندهید.

  • در پنل، بخش «افزونه‌ها و API»، چند کلید با نام بسازید (برچسب واقعی/آزمایشی). مقدار کلید فقط هنگام ساخت نمایش داده می‌شود و در سرور به‌صورت هش ذخیره است.
  • هر کلید را جدا باطل کنید؛ کلید باطل‌شده بلافاصله ۴۰۱ می‌گیرد. زمان آخرین استفادهٔ هر کلید در پنل دیده می‌شود.
  • «کلید قدیمی» حساب‌های قدیمی همچنان کار می‌کند و از همان بخش قابل چرخش یا ابطال است.

ساخت فاکتور

POST https://api.bolgram.ir/v1/payment/create (همان مسیر با پیشوند /api هم کار می‌کند). بدنه JSON است.

فیلدنوعتوضیح
amountعدد مثبت، الزامیمبلغ پایه. پیش‌فرض ریال است؛ با currency: "IRT" تومان حساب می‌شود. سیستم چند تومان یکتا به آن اضافه می‌کند تا واریز مشتری با همین فاکتور تطبیق داده شود.
currencyIRR | IRTواحد amount؛ پیش‌فرض IRR.
redirect_urlURL http/https، الزامیبازگشت مشتری بعد از پرداخت؛ invoice_id و status=paid به آن اضافه می‌شود.
cancel_urlURL http/httpsبازگشت در صورت انصراف، لغو یا انقضا.
webhook_urlURL httpsآدرس وب‌هوک همین فاکتور؛ اگر نفرستید، آدرس وب‌هوک فروشگاه در پنل استفاده می‌شود. آدرس‌های داخلی/خصوصی و http (به‌جز localhost در توسعه) رد می‌شوند.
cus_name، cus_emailمتناطلاعات اختیاری مشتری.
metadataشیء JSONحداکثر ۱ کیلوبایت؛ مثلاً شمارهٔ سفارش شما. در استعلام و وب‌هوک برمی‌گردد.
curl -X POST "https://api.bolgram.ir/v1/payment/create" \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"amount": 450000, "currency": "IRT", "redirect_url": "https://shop.example/thanks",
       "webhook_url": "https://shop.example/hooks/bolgram", "metadata": {"order_id": "1042"}}'

# 201 Created
{"status": true, "message": "Invoice created successfully.",
 "invoice_id": "PF...", "payment_url": "https://...",
 "amount": 4500280, "amount_toman": 450028, "invoice_status": "PENDING",
 "expires_at": "2026-10-06T10:52:31.000Z"}

amount در پاسخ، مبلغ قابل پرداخت به ریال (مبلغ شما + دنبالهٔ یکتا) است. فاکتور ۳۰ دقیقه اعتبار دارد.

استعلام فاکتور

POST https://api.bolgram.ir/v1/payment/verify با بدنهٔ {"invoice_id": "..."}. قبل از تحویل سفارش، حتی بعد از دریافت وب‌هوک، یک‌بار استعلام کنید و هر invoice_id را فقط یک‌بار تحویل دهید.

{"invoice_id": "PF...", "amount": 4500280, "amount_toman": 450028,
 "status": "COMPLETED", "invoice_status": "PAID", "paid": true,
 "transaction_id": "IR3F9A...", "payment_method": "mellat",
 "cus_name": "Ali", "metadata": {"order_id": "1042"}}

مقدار amount مبلغ یکتای قابل پرداخت به ریال است. برای تصمیم‌گیری از invoice_status یا paid استفاده کنید؛ status نگاشت سادهٔ قدیمی است (COMPLETED، PENDING، FAILED).

وب‌هوک و امضا

بعد از تأیید پرداخت، یک درخواست POST با بدنهٔ JSON به webhook_url فاکتور (یا آدرس وب‌هوک فروشگاه) فرستاده می‌شود. هر تلاش در پنل (بخش «وب‌هوک») با کد پاسخ و زمان ثبت می‌شود و می‌توانید دوباره بفرستید.

X-Bolgram-Signaturet=<unix>,v1=<hex> که v1 برابر HMAC-SHA256 کلید امضا روی رشتهٔ t + "." + body است. تا ۲۴ ساعت بعد از چرخش کلید، دو v1 (کلید جدید و قبلی) می‌آید؛ یکی از آن‌ها باید بخواند.
X-Bolgram-Deliveryشناسهٔ یکتای ارسال؛ در تلاش‌های مجدد همان می‌ماند. برای جلوگیری از پردازش تکراری ذخیره‌اش کنید.
X-Bolgram-Invoice-Idشناسهٔ فاکتور.
X-Bolgram-Eventinvoice.paid یا ping (آزمایشی).
{"event": "invoice.paid", "invoice_id": "PF...", "status": "true", "provider": "mellat",
 "trx_id": "IR3F9A...", "amount": 4500280, "timestamp": "2026-10-06T10:22:31.000Z",
 "metadata": {"order_id": "1042"}}

کلید امضا را از صفحهٔ «وب‌هوک» پنل بردارید (نمایش، کپی و چرخش). رویداد ping با status: "false" می‌آید و هرگز پرداخت نیست. همیشه بدنهٔ خام را امضا کنید و اگر اختلاف t با ساعت سرور شما بیش از ۵ دقیقه بود، درخواست را رد کنید.

# Node.js
const t = Number(/t=(\d+)/.exec(header)[1]);
const sigs = [...header.matchAll(/v1=([0-9a-f]+)/g)].map((m) => m[1]);
const expected = crypto.createHmac('sha256', SECRET).update(t + '.' + rawBody).digest('hex');
const ok = sigs.some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));

# PHP
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);   // سپس hash_equals با هر v1

# Python
expected = hmac.new(SECRET.encode(), f'{t}.'.encode() + raw_body, hashlib.sha256).hexdigest()

تلاش مجدد

اگر پاسخ ۲xx نرسد یا پاسخ در ۸ ثانیه نیاید، حداکثر ۶ تلاش انجام می‌شود، با فاصلهٔ ۱ دقیقه، ۱۰ دقیقه، ۱ ساعت، ۶ ساعت و ۱۶ ساعت (حدود ۲۳ ساعت). ریدایرکت دنبال نمی‌شود و زمان‌بندی تلاش‌ها با راه‌اندازی دوبارهٔ سرور از بین نمی‌رود. چون ممکن است یک رویداد بیش از یک‌بار برسد، پردازش شما باید ایدمپوتنت باشد.

وضعیت‌ها

invoice_statusمعنیstatus قدیمی
PENDINGدر انتظار واریزPENDING
PAIDپرداخت تأیید شدهCOMPLETED
EXPIREDمهلت تمام شدFAILED
CANCELLEDتوسط فروشنده لغو شدFAILED

خطاها

پاسخ خطا به شکل {"status": false, "message": "...", "errors": [...]} است (و در خطاهای سقف پلن/کیف پول فیلد code هم می‌آید).

400اعتبارسنجی بدنه ناموفق بود (مثلاً redirect_url نامعتبر یا webhook_url داخلی)؛ جزئیات در errors.
401کلید API ارسال نشده، نامعتبر یا باطل شده، یا فروشگاه فعال نیست.
402سقف پلن یا موجودی کیف پول اجازهٔ ساخت فاکتور نمی‌دهد (code را ببینید).
404فاکتور پیدا نشد یا متعلق به این فروشگاه نیست.
429تعداد درخواست بیش از حد مجاز است؛ بعد از چند ثانیه دوباره بفرستید.

محدودیت‌ها

  • هر آدرس IP حداکثر ۱۲۰ درخواست در دقیقه؛ بعد از آن پاسخ 429 می‌گیرد.
  • حداکثر ۱۰ کلید API فعال برای هر فروشگاه.
  • metadata حداکثر ۱ کیلوبایت؛ مبلغ باید مثبت باشد (ریال، یا تومان با currency).
  • صفحهٔ پرداخت هر فاکتور ۳۰ دقیقه باز است.

از پنل یک فاکتور بسازید و لینک صفحهٔ پرداخت را در دایرکت اینستاگرام یا پیام‌رسان بفرستید. مشتری بانکش را انتخاب می‌کند، کارت و مبلغ دقیق را می‌بیند و بعد از واریز، تأیید خودکار انجام می‌شود.

ووکامرس

افزونهٔ ووکامرس را از پنل (بخش «افزونه‌ها و API») دانلود کنید؛ آدرس سرور شما از قبل داخل آن گذاشته شده است. در وردپرس نصب و فعال کنید، سپس در «ووکامرس > تنظیمات > پرداخت > بولگرام» کلید API و کلید امضای وب‌هوک (از صفحهٔ «وب‌هوک» پنل) را وارد کنید. افزونه خودش فاکتور می‌سازد، مشتری را به صفحهٔ پرداخت می‌برد، امضای وب‌هوک را بررسی می‌کند و سفارش را فقط یک‌بار «پرداخت‌شده» می‌کند. کد منبع در integrations/woocommerce/bolgram-gateway است.

تلگرام و بله

در نسخهٔ فعلی، اعلان هر پرداخت موفق با تنظیم BALE_BOT_TOKEN و TELEGRAM_BOT_TOKEN روی سرور به ربات ارسال می‌شود. برای ربات فروش خودتان، فاکتور را با API بسازید و لینک پرداخت را به کاربر بدهید. ربات تعاملی برای ساخت فاکتور از داخل چت به‌زودی اضافه می‌شود.

SDKها

SDKهای PHP، Node.js و Python در پوشهٔ packages/ مخزن قرار دارند و همین endpointها را صدا می‌زنند.

اپ اندروید

اپ دریافت پیامک روی گوشی‌ای نصب می‌شود که پیامک بانک را دریافت می‌کند. فقط پیامک‌هایی که شبیه تراکنش بانکی‌اند ارسال می‌شوند و رمز پویا و کد تأیید هرگز ارسال نمی‌شود. اتصال با اسکن کد QR از بخش «دستگاه‌ها» در پنل انجام می‌شود. لینک دانلود از بازار و گوگل‌پلی پس از انتشار اینجا قرار می‌گیرد.

شورتکات آیفون

iOS اجازهٔ خواندن پیامک به اپ نمی‌دهد. با برنامهٔ Shortcuts یک اتوماسیون بسازید:

  1. در Shortcuts، بخش Automation، گزینهٔ Message را انتخاب کنید و فرستنده را شمارهٔ پیامک بانک قرار دهید.
  2. اکشن Get Contents of URL را اضافه کنید: روش POST، آدرس زیر، بدنهٔ JSON.
  3. گزینهٔ «اجرا بدون پرسیدن» را روشن کنید.
POST https://api.bolgram.ir/api/v1/device/sms/ingest
{"device_id": "<توکن دستگاه از پنل>", "sender": "<Shortcut Input: Sender>", "sms": "<Shortcut Input: Content>"}

توکن دستگاه فقط اجازهٔ ارسال پیامک را دارد، نه دسترسی به پنل یا پول. برای آیفون یک دستگاه جدا بسازید تا اگر گوشی گم شد، فقط همان را از پنل باطل کنید.

وضعیت سرویس

صفحهٔ وضعیت لحظه‌ای سرویس به‌زودی منتشر می‌شود. تا آن زمان در صورت مشکل از صفحهٔ تماس به پشتیبانی پیام دهید.

پشتیبانی تلگرام