# iTz Commerce Site Connector Kit

این پوشه برای مشتریانی است که می‌خواهند سایت فروش خودشان را به iTzAYDiN-BOT وصل کنند. سایت **اختیاری** است و نبودن آن هیچ اثری روی کار ربات ندارد.

## موارد اجباری
بعد از ساخت Connector از `iTz Commerce Hub` فقط این سه مقدار را در Environment سایت ذخیره کنید:

```env
ITZ_COMMERCE_API=https://BOT-DOMAIN/api/commerce.php
ITZ_COMMERCE_KEY=itz_site_xxxxxxxxx
ITZ_COMMERCE_SECRET=itz_wh_xxxxxxxxx
```

دامنه، IP، Bot Token و Credential شخصی سازنده داخل سورس Hard-code نشده‌اند.

## امضای درخواست
هر درخواست JSON باید این Headerها را داشته باشد:

- `X-iTz-Key`
- `X-iTz-Timestamp`
- `X-iTz-Signature`

Signature:

```text
HMAC-SHA256(timestamp + "\n" + raw_json_body, ITZ_COMMERCE_SECRET)
```

Timestamp بیشتر از ۵ دقیقه اختلاف پذیرفته نمی‌شود.

## API Actions

- `health`
- `catalog`
- `payment.methods`
- `order.create`
- `order.parameters`
- `payment.success`
- `payment.failed`
- `order.status`

## نکته پرداخت
سایت باید **اول پرداخت را با API رسمی درگاه خودش Verify کند** و فقط بعد از تایید واقعی، `payment.success` را برای ربات ارسال کند. Commerce API هیچ Merchant/API Key حساس ربات را به سایت نمایش نمی‌دهد.

## Order create نمونه

```php
require 'ItzCommerceClient.php';
$c = new ItzCommerceClient(
    getenv('ITZ_COMMERCE_API'),
    getenv('ITZ_COMMERCE_KEY'),
    getenv('ITZ_COMMERCE_SECRET')
);

$result = $c->createOrder([
    'external_order_id' => 'SHOP-10051',
    'product_id' => 3,
    'quantity' => 1,
    'customer' => [
        'external_customer_id' => 'customer-42',
        'telegram_id' => '123456789',
        'telegram_username' => 'example',
        'full_name' => 'Customer Name',
    ],
    'parameters' => [
        'username' => 'customer_user'
    ]
]);
```

## Sync برگشتی
ربات بعد از تغییر وضعیت سفارش تلاش می‌کند به این مسیر روی سایت POST بزند:

```text
https://YOUR-SITE/itz-commerce-webhook
```

فایل `itz-commerce-webhook.example.php` نمونه اعتبارسنجی امضای این درخواست است.

> برای انجام مطمئن‌تر و سالم‌تر اتصال سایت، در صورت نیاز با پشتیبانی `@itzaydin` هماهنگ کنید.
