از ساخت فاکتور تا
تحویل خودکار محصول

۱. شروع سریع

ترتیب درست راه‌اندازی

1. ۱
   ورود و ایمن‌سازی حساب

   وارد پنل شوید و رمز اولیه را تغییر دهید.

2. ۲
   ثبت کارت‌های بانکی

   کارت، نام صاحب حساب، وزن پخش و محدودیت‌های مبلغ را ثبت کنید.

3. ۳
   ساخت کلیدهای اتصال

   برای Backend یک API Key و برای هر گوشی یک Device Token جدا بسازید.

4. ۴
   تنظیم Webhook

   یک آدرس HTTPS عمومی و Signing Secret حداقل ۳۲ کاراکتری ثبت کنید.

5. ۵
   تست کامل

   یک فاکتور کم‌مبلغ بسازید، مبلغ دقیق را واریز کنید و تحویل محصول را بررسی کنید.

۲. پنل فروشنده

کارت‌ها و اتصال‌ها را تنظیم کنید

۳. اتصال سایت یا ربات

فاکتور را فقط از Backend بسازید

API Key نباید به JavaScript مرورگر، اپ مشتری، Git یا پیام‌رسان ارسال شود. سایت یا ربات شما باید از Backend خود درخواست زیر را بفرستد:

POST https://varizban.chipsomast.com/api/v1/invoices
Content-Type: application/json
X-Api-Key: YOUR_MERCHANT_API_KEY

{
  "merchantOrderId": "order-78452",
  "amountRials": 3600000,
  "idempotencyKey": "invoice-order-78452-v1",
  "metadata": {
    "customerId": "customer-19",
    "productId": "product-42"
  }
}

merchantOrderId و idempotencyKey باید برای هر سفارش یکتا باشند. اگر درخواست به‌دلیل خطای شبکه تکرار شد، همان idempotencyKey قبلی را ارسال کنید.

چه چیزی به مشتری نمایش داده شود؟

• نام بانک و نام صاحب حساب
• شماره کارت
• مبلغ payableAmountRials با تأکید «مبلغ را دقیقاً وارد کنید»
• زمان expiresAt و شناسه سفارش

{
  "publicId": "inv_example123",
  "requestedAmountRials": 3600000,
  "payableAmountRials": 3600010,
  "adjustmentRials": 10,
  "status": "Pending",
  "expiresAt": "2026-08-09T10:30:00Z",
  "payment": {
    "bankName": "نام بانک",
    "cardNumber": "4242424242424242",
    "holderName": "نام صاحب حساب"
  }
}

برای پیگیری وضعیت از GET /api/v1/invoices/{publicId} استفاده کنید؛ اما تحویل محصول فقط با Webhook انجام شود. لغو فقط برای فاکتور Pending ممکن است: POST /api/v1/invoices/{publicId}/cancel.

۴. اتصال گوشی با MacroDroid

اعلان موبایل‌بانک، روش پیشنهادی

1. در پنل فروشنده یک Device Token برای همان گوشی بسازید.
2. در MacroDroid یک Macro جدید بسازید؛ Trigger را روی Notification Received بگذارید.
3. فقط اپ موبایل‌بانک موردنظر را انتخاب و Notification Access را فعال کنید.
4. Action از نوع HTTP Request با Method برابر POST بسازید.
5. Header زیر و Content Type برابر application/json را وارد کنید.

X-Device-Token: DEVICE_TOKEN_SHOWN_ONCE

{
  "eventId": "notif-{not_app_package}-{system_time_ms}",
  "packageName": "{not_app_package}",
  "title": "{not_title}",
  "text": "{notification}",
  "receivedAt": "{year}-{month_digit}-{dayofmonth}T{hour_0}:{minute}:{second}+03:30"
}

۵. تحویل خودکار محصول

Webhook را قبل از تحویل محصول اعتبارسنجی کنید

پس از تأیید پرداخت، واریز بان یک درخواست POST به URL ثبت‌شده در پنل ارسال می‌کند:

X-Webhook-Id: evt_...
X-Webhook-Timestamp: 1785663900
X-Webhook-Signature: v1=HEX_HMAC_SHA256

امضا باید روی Body خام محاسبه شود:

HMAC_SHA256(signingSecret, timestamp + "." + rawRequestBody)

1. Body خام را پیش از Deserialize نگه دارید.
2. Timestamp قدیمی‌تر از پنج دقیقه را رد کنید.
3. امضا را با مقایسه ثابت‌زمان بررسی کنید.
4. X-Webhook-Id را یکتا ذخیره کنید؛ رویداد تکراری باید پاسخ 2xx بگیرد ولی تحویل تکرار نشود.
5. سفارش، invoiceId و payableAmountRials را با داده‌های ذخیره‌شده تطبیق دهید.
6. فقط پس از ثبت پایدار وضعیت، محصول را یک‌بار تحویل دهید.

۶. امنیت و عیب‌یابی

قبل از شروع فروش واقعی