# نمونه اتصال فروشگاه

همه نمونه‌ها ساخت فاکتور و دریافت وضعیت را انجام می‌دهند. کلید در سرور فروشگاه نگهداری می‌شود. مبلغ به صورت رشته ریالی است و همه زبان‌ها از شناسه درخواست ثابت request_id برای جلوگیری از فاکتور تکراری استفاده می‌کنند.

| زبان | فایل | پیش‌نیاز |
|---|---|---|
| Python | didban_client.py | Python 3.10+؛ بدون بسته اضافی |
| JavaScript / Node.js | didban-client.mjs + store-example.mjs | Node.js 20+؛ بدون بسته اضافی |
| PHP | DidbanClient.php + store-example.php | PHP 8.1+ و cURL |
| Go | store-example.go | Go 1.20+؛ بدون بسته اضافی |
| C# | dotnet/Program.cs + dotnet/DidbanExample.csproj | .NET 8 SDK |

برای اجرای هر نمونه، متغیرهای محیطی `DIDBAN_API_URL` و `DIDBAN_API_KEY` را در همان فرایند تنظیم کنید. نمونه‌ها در حالت پیش‌فرض به سرویس محلی آزمایشی 4327 وصل می‌شوند؛ پنل اصلی روی 4321 است. برای سرویس اصلی مقدار URL را `http://127.0.0.1:4321` بگذارید و کلید را از همان پنل بسازید. کلیدهای دو پایگاه داده با هم قابل استفاده نیستند.

```text
python didban_client.py
node store-example.mjs
php store-example.php
go run store-example.go
dotnet run --project dotnet/DidbanExample.csproj
```

کلید نمونه را در کد ثابت ننویسید و این فایل‌ها را در مرورگر اجرا نکنید. آدرس انتشار سرویس باید HTTPS باشد. هیچ نمونه‌ای اعتبارسنجی گواهی را خاموش نمی‌کند یا کلید را در آدرس می‌فرستد. انتقال خودکار درخواست به آدرس دیگر غیرفعال است.

پس از ساخت، `id` و `order_id` تولیدشده و مبلغ نهایی پاسخ را کنار شماره سفارش داخلی فروشگاه ذخیره و مشتری را به `payment_url` هدایت کنید. در خطای ارتباط، همان request_id و همان اطلاعات را دوباره ارسال کنید؛ شماره جدید نسازید. مبلغ نهایی `amount_rial` با مبلغ پایه تفاوت دارد و مشتری باید مبلغ نهایی را واریز کند.

در وضعیت `MATCHED_REVIEW` واریز نیازمند بررسی است؛ `paid=true` فقط با تأیید بانکی فاکتور واقعی صادر می‌شود. `PAID` آزمایشی یا `test_payment` دلیل پرداخت واقعی نیستند. پیش از تحویل، mode=live و paid=true و شناسه و مبلغ سفارش ذخیره‌شده را بررسی و تحویل را یکتا ثبت کنید.

جزئیات مسیرها، خطاها و محدودیت‌ها در `../MERCHANT-API.md` آمده است. یک API مشترک برای همه زبان‌ها ارائه شده؛ این نمونه‌ها به API بانک یا رمز حساب دسترسی مستقیم ندارند.

## دریافت وب‌هوک

فایل‌های کامل گیرنده PHP، Python و Node.js در پوشه `webhooks` قرار دارند. راهنمای نصب، تنظیم HTTPS و کلید امضا، ثبت سفارش، مقابله با ارسال تکراری و صف تحویل در [webhooks/README.md](webhooks/README.md) است. نمونه‌های ساخت فاکتور باید شناسه فاکتور و مبلغ نهایی پاسخ را قبل از نمایش پرداخت به مشتری در پایگاه سفارش ذخیره کنند.

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

عنوان فاکتور از نام فروشگاه در تنظیمات گرفته می‌شود؛ کلاینت‌ها عنوان ارسال نمی‌کنند. آرگومان اول متد ساخت، request_id ثابت و ذخیره‌شدهٔ همان تلاش پرداخت است. رشته‌های نمونه را برای هر خرید جدید با شناسه تازه جایگزین کنید؛ در تکرار همان درخواست آن را عوض نکنید.