# اتصال CalcGard به ربات تلگرام یا بله

## جریان پیشنهادی

1. مشتری در ربات سفارش ایجاد می‌کند.
2. ربات همان لحظه با API CalcGard یک Payment با `external_id` یکتا و مبلغ ریالی می‌سازد.
3. ربات شماره کارت مقصد، مبلغ دقیق و مهلت را نمایش می‌دهد.
4. پس از رسیدن SMS، CalcGard سفارش را تطبیق می‌دهد.
5. وب‌هوک `payment.paid` به ربات می‌رسد.
6. ربات امضا و `event_id` را بررسی می‌کند، وضعیت داخلی سفارش را اتمیک تغییر می‌دهد و سپس محصول را تحویل می‌دهد.

## قواعد ضروری

- هر سفارش فقط یک `external_id` یکتا داشته باشد.
- مبلغ را از سمت سرور خودتان به CalcGard بدهید؛ مبلغ ارسالی کاربر را اعتماد نکنید.
- وب‌هوک را idempotent کنید؛ دریافت دوباره یک event نباید تحویل دوباره ایجاد کند.
- قبل از تحویل، علاوه بر وب‌هوک می‌توانید وضعیت Payment را از API استعلام کنید.
- اگر چند سفارش هم‌مبلغ هم‌زمان دارید، CalcGard عمداً خودکار تأیید نمی‌کند. زمان سفارش‌ها را کوتاه یا مبلغ‌های متمایز تعریف کنید.
- شناسه تلگرام/بله و شناسه سفارش داخلی را در `metadata` بگذارید؛ اطلاعات حساس قرار ندهید.

نمونه‌های آماده در این فایل‌ها هستند:

- `examples/php/CalcGardClient.php`
- `examples/php/telegram_webhook.php`
- `examples/python/calcgard_client.py`
- `examples/node/calcgard-client.mjs`