sobhansgh/torob-sync

اتصال فروشگاه‌های لاراولی به ترب (Torob) بر اساس Product API v3، احراز هویت JWT و وبهوک به‌روزرسانی محصول

v1.0.0 2026-08-22 16:04 UTC

Requires

• php: ^8.1
• ext-sodium: *
• firebase/php-jwt: ^6.9
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

MIT

• Sobhan Ghasemi

• laravel
• e-commerce
• webhook
• jwt
• product-feed
• torob
• torob-sync
• ترب

Published on Packagist.org on 2026-08-22 16:25 UTC

README

اتصال هر فروشگاه لاراولی به ترب (Torob) بر اساس آخرین نسخه‌ی API رسمی ترب:

• ✅ Product API v3 — endpoint دریافت محصولات توسط ترب (لیست صفحه‌بندی‌شده + جستجو با URL/شناسه یکتا)
• ✅ احراز هویت JWT (EdDSA/ed25519) — طبق راهنمای توکن ترب، به‌صورت کامل و خودکار
• ✅ وبهوک به‌روزرسانی محصول — اطلاع‌رسانی سریع افزودن/ویرایش محصول بدون نیاز به کراول دوره‌ای
• ✅ پشتیبانی از محصولات ساده و متغیر (Variant) از طریق product_group_id

شما فقط باید به پکیج بگویید محصولات‌تان از کجا می‌آیند؛ باقی کارها (مسیر، احراز هویت، صفحه‌بندی، قالب پاسخ) توسط پکیج مدیریت می‌شود.

سازگار با Laravel 10, 11 و 12 و PHP 8.1+.

نصب

composer require sobhansgh/torob-sync

پکیج به‌صورت خودکار توسط Laravel شناسایی می‌شود (Package Auto-Discovery). سپس افزونه‌ی sodium باید در PHP شما فعال باشد (برای اعتبارسنجی امضای EdDSA):

php -m | grep sodium

اگر فعال نبود، در php.ini این خط را از حالت کامنت خارج کنید: extension=sodium

انتشار فایل کانفیگ

php artisan vendor:publish --tag=torob-sync-config

فایل config/torob-sync.php در پروژه‌ی شما ساخته می‌شود.

راه‌اندازی سریع (۳ مرحله)

مرحله ۱: ساخت کلاس اتصال محصولات

php artisan make:torob-provider

این دستور فایل app/Torob/TorobProductProvider.php را می‌سازد. این تنها فایلی است که باید تکمیل کنید:

<?php

namespace App\Torob;

use App\Models\Product;
use Sobhansgh\TorobSync\Contracts\TorobProductProvider as TorobProductProviderContract;
use Sobhansgh\TorobSync\Support\TorobProduct;

class TorobProductProvider implements TorobProductProviderContract
{
    public function paginate(int $page, string $sort): array
    {
        $query = Product::query()->where('is_active', true);

        $sort === 'date_updated_desc'
            ? $query->orderByDesc('updated_at')
            : $query->orderByDesc('created_at');

        return [
            'total' => $query->count(),
            'products' => $query->forPage($page, 100)->get()
                ->map(fn (Product $p) => $this->toTorobProduct($p))
                ->all(),
        ];
    }

    public function findByUrls(array $urls): array
    {
        return Product::query()
            ->whereIn('canonical_url', $urls)
            ->get()
            ->map(fn (Product $p) => $this->toTorobProduct($p))
            ->all();
    }

    public function findByUniques(array $uniques): array
    {
        return Product::query()
            ->whereIn('id', $uniques)
            ->get()
            ->map(fn (Product $p) => $this->toTorobProduct($p))
            ->all();
    }

    protected function toTorobProduct(Product $product): TorobProduct
    {
        return TorobProduct::make(
            pageUnique: (string) $product->id,
            pageUrl: route('product.show', $product->slug)
        )
            ->title($product->title)
            ->price(current: $product->price, old: $product->old_price)
            ->availability($product->stock > 0)
            ->images($product->images)
            ->category($product->category?->name)
            ->spec($product->specs ?? [])
            ->dateAdded($product->created_at)
            ->dateUpdated($product->updated_at);
    }
}

برای محصولات ساده، همین کافی است. برای محصولات متغیر (مثلاً چند رنگ)، در ادامه توضیح داده شده.

مرحله ۲: تنظیم .env

TOROB_PROVIDER=App\Torob\TorobProductProvider

# فقط اگر می‌خواهید وبهوک ارسال کنید (اختیاری):
TOROB_WEBHOOK_TOKEN=your-token-from-torob-support

مرحله ۳: ثبت آدرس نزد ترب

آدرس endpoint شما به‌صورت پیش‌فرض این خواهد بود (مطابق مثال‌های مستندات ترب):

https://your-domain.com/torob_api/v3/products

این آدرس را در پنل/فرم ثبت‌نام ترب وارد کنید تا ترب شروع به دریافت محصولات شما کند. کلید عمومی ترب و اعتبارسنجی JWT به‌صورت کامل در پکیج پیاده‌سازی شده و نیازی به کار اضافه نیست.

پشتیبانی از محصولات متغیر (Variant)

طبق مستندات ترب، واریانت‌های یک محصول (مثلاً رنگ‌های مختلف) باید یک product_group_id مشترک و page_unique جداگانه داشته باشند:

protected function toTorobProduct(ProductVariant $variant): TorobProduct
{
    return TorobProduct::make(
        pageUnique: (string) $variant->id,        // برای هر واریانت متفاوت
        pageUrl: route('product.show', $variant->slug)
    )
        ->groupId((string) $variant->product_id)   // برای همه واریانت‌ها یکسان
        ->title($variant->product->title.' - '.$variant->color)
        ->price(current: $variant->price)
        ->availability($variant->stock > 0)
        ->images($variant->images)
        ->spec(['رنگ' => $variant->color, 'سایز' => $variant->size]);
}

برای محصول ساده فقط کافی است groupId() را صدا نزنید.

ارسال وبهوک (اطلاع‌رسانی سریع تغییر محصول)

به‌جای منتظر ماندن برای کراول دوره‌ای ترب، هر بار که محصولی اضافه یا ویرایش شد می‌توانید به ترب اطلاع دهید (نیازمند توکن که از پشتیبانی ترب دریافت می‌کنید):

use Sobhansgh\TorobSync\Facades\Torob;

// یک محصول
Torob::notifyOne(
    pageUrl: route('product.show', $product->slug),
    pageUnique: (string) $product->id
);

// چند محصول با هم (خودکار در دسته‌های ۱۰۰تایی ارسال می‌شود)
Torob::notify([
    ['page_url' => '...', 'page_unique' => '...'],
    ['page_url' => '...', 'page_unique' => '...'],
]);

بهترین‌جا برای صدا زدن این متد، Observer مدل محصول شماست (رویدادهای created و updated):

// app/Observers/ProductObserver.php
use Sobhansgh\TorobSync\Facades\Torob;

class ProductObserver
{
    public function saved(Product $product): void
    {
        Torob::notifyOne(
            route('product.show', $product->slug),
            (string) $product->id
        );
    }
}

طبق مستندات ترب، محدودیت نرخ درخواست وبهوک ۲۰ درخواست در دقیقه به ازای هر فروشگاه است؛ در صورت نیاز به ارسال حجم بالا، صف (Queue) لاراول را برای این متد استفاده کنید.

متغیرهای محیطی (.env)

متغیر	توضیح	پیش‌فرض
TOROB_PROVIDER	کلاس اتصال محصولات شما	App\Torob\TorobProductProvider
TOROB_ROUTE_PREFIX	پیشوند آدرس endpoint	torob_api/v3
TOROB_ROUTE_DOMAIN	دامنه‌ی اختصاصی روت (اختیاری)	—
TOROB_PUBLIC_KEY	کلید عمومی ترب برای JWT	مقدار رسمی ترب
TOROB_AUD	مقدار دستی aud (فقط پشت پروکسی خاص)	Host درخواست
TOROB_WEBHOOK_URL	آدرس وبهوک ترب	https://api.torob.com/update/webhook/v1/
TOROB_WEBHOOK_TOKEN	توکن وبهوک (از پشتیبانی ترب)	—

چگونه کار می‌کند؟

1. ترب یک درخواست POST با هدر X-Torob-Token (JWT با الگوریتم EdDSA) به route.prefix + /products شما می‌زند.
2. میدل‌ور داخلی پکیج (VerifyTorobToken) امضا، تاریخ انقضا و aud توکن را با کلید عمومی ترب اعتبارسنجی می‌کند.
3. بسته به بدنه‌ی درخواست، یکی از متدهای paginate / findByUrls / findByUniques از کلاس Provider شما صدا زده می‌شود.
4. پکیج خروجی را دقیقاً مطابق فرمت torob_api_v3 قالب‌بندی و برمی‌گرداند.

تست دستی endpoint

curl -X POST https://your-domain.com/torob_api/v3/products \
     -H "Content-Type: application/json" \
     -H "X-Torob-Token: [توکن نمونه از ترب]" \
     -H "X-Torob-Token-Version: 1" \
     -d '{"page": 1, "sort": "date_added_desc"}'

منابع

• Product API v3
• راهنمای توکن JWT
• وبهوک به‌روزرسانی محصول

توسعه‌دهنده

ساخته‌شده توسط Sobhan Ghasemi — GitHub

لایسنس

این پکیج تحت لایسنس MIT منتشر شده است.