API توسعه‌دهندگان بایداکس

تست رایگان

هر دو گزینهٔ زیر رایگان هستند و به همان /api/v1 می‌روند که کد شما استفاده می‌کند — ولی خروجی‌شان فرق دارد:

درخواست

—

پاسخ

—

کلید شما فقط در همین صفحه و در حافظهٔ مرورگر شما استفاده می‌شود و جایی ذخیره نمی‌شود.

SDK — کتابخانهٔ اتصال

کلاینت تک‌فایلی برای زبان دلخواه‌تان — کپی یا دانلود کنید، bd_live_XXXX را با کلید خودتان و PRODUCT_ID را با شناسهٔ محصول (تب «محصولات») جایگزین کنید. هر سه SDK از حالت آزمایشی (test)، Idempotency-Key و انتظار برای آماده‌شدن سند پشتیبانی می‌کنند.

مرجع Endpoint ها

احراز هویت: هدر Authorization: Bearer bd_live_...

هر دو فهرست (/products و /documents) صفحه‌بندی دارند: پارامترهای page و per_page، و در پاسخ page، per_page، total و total_pages. پیش‌فرض per_page برای محصولات ۱۰۰ و برای سندها ۵۰ است و حداکثر ۲۰۰ — مقدار بزرگ‌تر خطای 422 می‌گیرد.

هزینهٔ هر محصول: در /products فیلد price «قیمت فروش همان محصول در سایت» است — یعنی چیزی که خریدار می‌پردازد، نه هزینهٔ شما. هزینهٔ خودتان برای هر سند در api_cost می‌آید (با ریز آن در api_cost_breakdown) و شامل احراز هویت‌های الزامی همان محصول هم هست: محصولی که هم شاهکار و هم زحل را الزامی کرده باشد ۴۵٬۰۰۰ تومان برایتان هزینه دارد، نه ۲۵٬۰۰۰.

تطبیق حساب: /documents پارامتر since را می‌پذیرد — ?since=2026-08-17T12:21:17Z یا فقط ?since=2026-08-17 — و فقط سندهای ساخته‌شده از آن لحظه به بعد را برمی‌گرداند. برای همگام‌سازی افزایشی با سیستم خودتان، آخرین created_utc که دیده‌اید را نگه دارید و دفعهٔ بعد همان را بفرستید.

تاریخ‌ها: created_at و ready_at رشتهٔ شمسی به وقت تهران‌اند و برای کتابخانه‌های تاریخ غیرایرانی قابل تجزیه نیستند. کنار هرکدام created_utc و ready_utc به قالب ISO-8601 و ساعت UTC هم می‌آید (2026-08-17T12:21:17Z) — در کد خود همین‌ها را بخوانید. فیلدهای شمسی حذف نمی‌شوند. expires_epoch هم مثل قبل ثانیهٔ یونیکس است.

بدنهٔ درخواست stamp

هدرها

• Idempotency-Key (پیشنهادی): شناسهٔ سفارش خودتان. تکرار همان درخواست (مثلاً بعد از قطعی شبکه) سند قبلی را برمی‌گرداند و هزینهٔ دوباره کسر نمی‌شود.
• در پاسخ: X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Window — سهم باقی‌ماندهٔ شما در پنجرهٔ جاری. با اینها می‌توانید قبل از خوردن ۴۲۹ سرعت را کم کنید.

کدهای خطا

هر پاسخ خطا علاوه بر متن detail، یک code ثابت و ماشین‌خوان دارد. روی code شرط بگذارید، نه روی متن پیام — متن پیام ممکن است بازنویسی شود، code هرگز.

{
  "detail": "موجودی کیف پول کافی نیست | Insufficient wallet balance (required: 25000 Toman)",
  "code": "insufficient_balance",
  "status": 402
}

احراز هویت (شاهکار و زحل)

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

برای اینکه بدانید هر محصول چه می‌خواهد، GET /api/v1/products را بخوانید — هر محصول kyc_required و requires_birth_date دارد. لازم نیست حدس بزنید.

هزینه وقتی احراز هویت ناموفق است

شاهکار و زحل بابت هر استعلام انجام‌شده از ما هزینه می‌گیرند — حتی وقتی جواب «عدم انطباق» باشد. بنابراین:

یعنی هرگز بابت سندی که تحویل نگرفته‌اید پول نمی‌دهید؛ ولی استعلامی که واقعاً انجام شده هزینه دارد. اگر سرویس استعلام قطع باشد هیچ مبلغی کسر نمی‌شود و می‌توانید بی‌خطر دوباره بفرستید.

پاسخ خطای احراز هویت خودش می‌گوید چقدر کسر شده:

HTTP 409
{
  "detail": "کد ملی و شماره موبایل مطابقت ندارند | ...",
  "code": "shahkar_mismatch",
  "status": 409,
  "charged": 10000,
  "kyc": {
    "ran": ["shahkar"],
    "stamp_charged": false,
    "billed_actions": [{ "action": "shahkar_verify", "price": 10000 }]
  }
}

در پاسخ سند هم charged (هزینهٔ سند — همانی که در صورت خطای تولید برمی‌گردد)، kyc_charged (هزینهٔ استعلام — هرگز برنمی‌گردد، چون استعلام واقعاً انجام شده) و charged_total جدا گزارش می‌شوند.

💡 با "test": true هیچ استعلامی انجام نمی‌شود و چیزی کسر نمی‌شود — فقط would_charge_breakdown می‌گوید که اگر واقعی بفرستید چقدر می‌شود. برای ساختن و اشکال‌زدایی اتصال، همیشه از همین حالت استفاده کنید.

اعلان خودکار (Webhook)

سند شما چند ثانیه پس از درخواست آماده می‌شود. دو راه دارید بفهمید کِی آماده شد:

می‌توانید هر دو را با هم داشته باشید — و اگر اعلان نرسید، پرسیدن همیشه جواب درست را می‌دهد.

راه‌اندازی در چهار قدم

1. در تب «کلیدها و مصرف»، روبه‌روی کلیدتان دکمهٔ «فعال‌سازی» را بزنید و آدرس https خودتان را وارد کنید.
2. یک کلید امضا (whsec_…) نمایش داده می‌شود — فقط همین یک بار. همان‌جا ذخیره‌اش کنید.
   گمش کردید؟ آدرس را خالی ثبت کنید (اعلان غیرفعال می‌شود) و دوباره ثبتش کنید؛ کلید امضای تازه ساخته می‌شود و کلید قبلی دیگر معتبر نیست. ثبت دوبارهٔ آدرس با کلید موجود، کلید را عوض نمی‌کند — پس گیرنده‌ای که تازه راه انداخته‌اید نمی‌شکند.
3. در سرور خودتان امضا را بررسی کنید (نمونهٔ کد پایین). بدون این کار هر کسی می‌تواند برای شما «سند آماده شد» بفرستد.
4. سریع پاسخ 2xx بدهید و کار سنگین را بعد از پاسخ انجام دهید.

چه چیزی دریافت می‌کنید

سند آماده شد:

POST https://your-site.example/buydocs-hook

{
  "event": "document.ready",
  "document_id": "d3f1c2...",
  "status": "ready",
  "download_url": "https://buydocs.ir/api/v1/documents/.../download?exp=...&sig=...",
  "expires_epoch": 1780000000,
  "charged": 25000,
  "refunded": false,
  "error": null
}

سند ناموفق بود (مبلغ سند خودکار برگشته است):

{
  "event": "document.failed",
  "document_id": "d3f1c2...",
  "status": "failed",
  "download_url": null,
  "expires_epoch": 1780000000,
  "charged": 25000,
  "refunded": true,
  "error": "watermark engine timeout"
}

این بدنه فقط charged (هزینهٔ سند) را دارد. برای تفکیک هزینهٔ استعلام، GET /api/v1/documents/{id} را بخوانید که kyc_charged و charged_total هم دارد.

بررسی امضا (الزامی)

امضا برابر است با HMAC-SHA256 روی رشتهٔ "<timestamp>.<بدنهٔ خام>" با کلید امضا. بدنه را قبل از JSON-parse و بدون هیچ تغییری (raw) امضا کنید — یک فاصله یا مرتب‌سازی دوبارهٔ کلیدها، امضا را خراب می‌کند.

// PHP
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_BUYDOCS_TIMESTAMP'];
$mine = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $SECRET);
if (!hash_equals($mine, $_SERVER['HTTP_X_BUYDOCS_SIGNATURE'])) { http_response_code(403); exit; }
if (abs(time() - (int)$ts) > 300) { http_response_code(403); exit; }   // replay
echo 'ok';   // هر پاسخ 2xx یعنی دریافت شد

# Python (Flask)
raw = request.get_data()                     # RAW bytes, before any parsing
ts  = request.headers.get('X-BuyDocs-Timestamp', '')
mine = 'sha256=' + hmac.new(SECRET.encode(),
                            ts.encode() + b'.' + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(mine, request.headers.get('X-BuyDocs-Signature', '')):
    return '', 403
if abs(time.time() - int(ts or 0)) > 300:
    return '', 403
return 'ok', 200

// Node (Express) — express.raw(), NOT express.json(): the raw body is what is signed
app.post('/buydocs-hook', express.raw({ type: '*/*' }), (req, res) => {
  const ts   = req.get('X-BuyDocs-Timestamp') || '';
  const sig  = req.get('X-BuyDocs-Signature') || '';
  const mine = 'sha256=' + crypto.createHmac('sha256', SECRET)
                                 .update(ts + '.' + req.body.toString('utf8'))
                                 .digest('hex');
  if (mine.length !== sig.length ||
      !crypto.timingSafeEqual(Buffer.from(mine), Buffer.from(sig))) return res.sendStatus(403);
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(403);
  res.sendStatus(200);                       // answer first, work afterwards
  const evt = JSON.parse(req.body.toString('utf8'));
});

آدرس شما باید چه شکلی باشد

• فقط https، و فقط پورت 443 یا 8443.
• باید به یک آدرس عمومی اشاره کند. دامنه‌ای که به 127.0.0.1 یا هر IP داخلی حل شود پذیرفته نمی‌شود — هم موقع ثبت، هم دوباره پیش از هر ارسال بررسی می‌شود.
• بدون نام کاربری/رمز در خود آدرس، و حداکثر ۵۰۰ کاراکتر.
• ⚠️ ریدایرکت دنبال نمی‌شود. اگر آدرس‌تان 301/302 بدهد — مثل /hook که به /hook/ می‌رود، یا دامنهٔ بدون www که به www می‌رود — تحویل ناموفق حساب می‌شود. آدرس نهایی را ثبت کنید.

نمونهٔ یک آدرس درست — مسیر و کوئری‌استرینگ آزاد است؛ آنچه اهمیت دارد پروتکل، دامنه و پورت است:

https://yourshop.ir/webhooks/buydocs

و آدرس‌هایی که پذیرفته نمی‌شوند، با همان پیامی که هنگام ثبت می‌گیرید:

⚠️ یک حالت که در ثبت قبول می‌شود ولی در ارسال شکست می‌خورد: آدرسی که ریدایرکت می‌دهد — مثلاً https://yourshop.ir/hook که به https://www.yourshop.ir/hook منتقل می‌شود. همان آدرس نهایی را ثبت کنید. همچنین اگر دامنهٔ شما هم رکورد A عمومی دارد و هم AAAA داخلی، رد می‌شود: همهٔ آدرس‌هایی که دامنه به آن‌ها حل می‌شود باید عمومی باشند.

زمان‌بندی، تلاش مجدد و تکرار

• هر تلاش حداکثر ۵ ثانیه برای برقراری اتصال و ۱۰ ثانیه در مجموع فرصت دارد. اگر گیرندهٔ شما اول کار سنگین می‌کند و بعد پاسخ می‌دهد، تحویل ناموفق می‌شود — اول 200 بدهید، بعد کارتان را انجام دهید.
• ناموفق شد؟ ۲ ثانیه بعد تلاش دوم، ۶ ثانیه بعد تلاش سوم. در مجموع ۳ تلاش — بعد از آن رها می‌شود و دیگر تلاشی نخواهد شد.
• موفق یعنی هر کد ۲xx. هر چیز دیگری — ۳xx (ریدایرکت)، ۴xx، ۵xx، تایم‌اوت، خطای TLS — ناموفق است.
• ممکن است یک رویداد بیش از یک بار برسد؛ با document_id کار خود را idempotent کنید (هر تلاش X-BuyDocs-Delivery جداگانه دارد، پس آن را برای این کار به‌کار نبرید).

اعلان نرسید — کجا را نگاه کنم؟

در GET /api/v1/documents هر سطر یک callback_status دارد:

اعلان به کلیدی وابسته است که سند را ساخته — اگر کلید را عوض کنید، سندهای در جریانِ کلید قبلی همچنان به آدرس ثبت‌شدهٔ همان کلید اعلام می‌شوند.

اعلان یک راحتی است، نه منبع حقیقت. سند حتی وقتی هیچ اعلانی تحویل داده نشود تولید می‌شود، پرداخت شده است و از GET /api/v1/documents/{id} قابل دریافت است. برای تطبیق نهایی و حسابداری همیشه همان را ملاک بگیرید.

نکات مهم

• سندها با همان موتور واترمارک بایداکس تولید می‌شوند: نام، موبایل و در صورت ارسال، کد ملی مشتری روی صفحات درج و اثر انگشت دیجیتال ثبت می‌شود.
• فایل تولیدشده و لینک آن پس از انقضا حذف می‌شوند — لینک را به‌موقع تحویل مشتری دهید.
• اگر تولید سند به هر دلیلی شکست بخورد، مبلغ به‌صورت خودکار به کیف پول برمی‌گردد (فیلد refunded).
• برای پشتیبانی فنی از صفحهٔ تماس با ما پیام بدهید.