PHPackages                             leadora/agents-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. leadora/agents-api

ActiveLibrary[API Development](/categories/api)

leadora/agents-api
==================

PHP client for the Leadora agent panel API

08PHP

Since Jul 10Pushed 2w agoCompare

[ Source](https://github.com/behzad-azizan/leadora-agents-api)[ Packagist](https://packagist.org/packages/leadora/agents-api)[ RSS](/packages/leadora-agents-api/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

leadora/agents-api
==================

[](#leadoraagents-api)

کلاینت PHP برای API پنل نمایندگی لیدورا (`/api/v1`).

نصب
---

[](#نصب)

```
composer require leadora/agents-api
```

توسعه محلی:

```
{
    "repositories": [
        {
            "type": "path",
            "url": "/home/behzad/Documents/php-projects/leadora-agents-api"
        }
    ],
    "require": {
        "leadora/agents-api": "@dev"
    }
}
```

راه‌اندازی
----------

[](#راه‌اندازی)

```
use Leadora\Agents\LeadoraClient;

$client = LeadoraClient::create(
    baseUrl: env('LEADORA_BASE_URL'),   // مثلا https://api.leadora.example
    apiToken: env('LEADORA_API_TOKEN'), // توکن نماینده
);
```

همه درخواست‌ها با هدر `Authorization: Bearer ` احراز هویت می‌شوند. هر endpoint یک scope مشخص نیاز دارد که باید روی توکن فعال باشد.

فهرست endpointها
----------------

[](#فهرست-endpointها)

متد کلاینتHTTPScopeIdempotency-Key`profile()->get()``GET /api/v1/agent/profile``profile.read`—`users()->register()``POST /api/v1/users``users.write`—`leads()->preview()``POST /api/v1/leads/preview``preview.create`—`leads()->naturalLanguagePreview()``POST /api/v1/leads/natural-language-preview``preview.create`—`leads()->campaignMessagePreview()``POST /api/v1/leads/campaign-message-preview``preview.create`—`leads()->quote()``POST /api/v1/leads/quote``quote.create`—`orders()->create()``POST /api/v1/orders``orders.create`الزامی`orders()->pay()``POST /api/v1/orders/{id}/pay``orders.pay`الزامی`orders()->createExport()``POST /api/v1/orders/{id}/exports``exports.create`الزامی`exports()->get()``GET /api/v1/exports/{id}``exports.read`—`exports()->download()``GET /api/v1/exports/{id}/download``exports.read`—۱. پروفایل نماینده و موجودی کیف پول
-----------------------------------

[](#۱-پروفایل-نماینده-و-موجودی-کیف-پول)

```
$profile = $client->profile()->get();

$profile->agent->id;              // agt_...
$profile->agent->status;          // active | suspended | disabled
$profile->wallet->balanceAmount;  // ریال (int)
```

۲. ثبت کاربر بعد از signup
--------------------------

[](#۲-ثبت-کاربر-بعد-از-signup)

ثبت کاربر upsert است؛ `external_user_id` تکراری برای همان نماینده، کاربر قبلی را به‌روزرسانی می‌کند.

```
use Leadora\Agents\Users\RegisterUserRequest;

$user = $client->users()->register(new RegisterUserRequest(
    externalUserId: (string) $localUser->id,
    mobile: $localUser->mobile,        // اختیاری
    email: $localUser->email,          // اختیاری
    fullName: $localUser->full_name,   // اختیاری
    metadata: ['plan' => 'gold'],      // اختیاری
));

$leadoraUserId = $user->id; // usr_...
```

۳. پیش‌نمایش تعداد لید
----------------------

[](#۳-پیش‌نمایش-تعداد-لید)

```
use Leadora\Agents\Filter\LeadFilter;
use Leadora\Agents\Leads\PreviewRequest;

$filter = new LeadFilter(
    provinceIds: [8],
    cityIds: [301],
    gender: 'male',            // male | female | unknown
    ageFrom: 25,
    ageTo: 40,
    mobileOperatorIds: [1],
    mobilePrefixes: [912],     // پیش‌شماره سه‌رقمی
);

$preview = $client->leads()->preview(new PreviewRequest(
    filter: $filter,
    userId: $leadoraUserId,                          // اختیاری
    countType: PreviewRequest::COUNT_TYPE_ESTIMATED, // exact | estimated
));

$preview->matchedCount;
$preview->countType;   // exact | estimated | placeholder
$preview->filterHash;
```

۳.۱ پیش‌نمایش با زبان طبیعی
---------------------------

[](#۳۱-پیش‌نمایش-با-زبان-طبیعی)

```
use Leadora\Agents\Leads\NaturalLanguagePreviewRequest;

$nl = $client->leads()->naturalLanguagePreview(new NaturalLanguagePreviewRequest(
    naturalLanguageIntent: 'شماره مردان ۲۰ تا ۶۰ سال ساکن تهران و اصفهان که در حوزه لوازم آرایشی یا عروسی کار می‌کنند',
    userId: $leadoraUserId,
    countType: NaturalLanguagePreviewRequest::COUNT_TYPE_ESTIMATED,
));

$nl->resolvedFilter;     // فیلتر ساختاریافته نهایی
$nl->appliedFilters;     // توضیح فارسی فیلترها
$nl->matchedCount;
$nl->interpretationFa;
```

۳.۲ پیشنهاد مخاطب از روی متن پیام
---------------------------------

[](#۳۲-پیشنهاد-مخاطب-از-روی-متن-پیام)

```
use Leadora\Agents\Leads\CampaignMessagePreviewRequest;

$suggested = $client->leads()->campaignMessagePreview(new CampaignMessagePreviewRequest(
    campaignMessage: 'فروش ویژه لوازم آرایشی با ۳۰٪ تخفیف فقط تا آخر هفته',
    userId: $leadoraUserId,
));

$suggested->resolvedFilter;
$suggested->messageFa;
$suggested->matchedCount;
```

برای فعال‌سازی، ادمین باید در تنظیمات سیستم این کلیدها را ست کند:

- `openai_api_key`
- `openai_model` (پیش‌فرض: `gpt-4o-mini`)
- `openai_enabled` (`true` / `false`)

۴. گرفتن پیش‌فاکتور (قیمت قفل‌شده)
----------------------------------

[](#۴-گرفتن-پیش‌فاکتور-قیمت-قفل‌شده)

```
use Leadora\Agents\Leads\QuoteRequest;

$quote = $client->leads()->quote(new QuoteRequest(
    userId: $leadoraUserId,   // الزامی — usr_...
    filter: $filter,
    requestedCount: 1000,
));

$quote->id;           // qt_...
$quote->unitPrice;    // ریال
$quote->totalAmount;  // ریال
$quote->expiresAt;    // RFC3339 — قیمت تا این زمان معتبر است
$quote->pricingBreakdown->baseUnitPrice;
$quote->pricingBreakdown->taxPercent;
$quote->pricingBreakdown->multipliers; // [key, value]
```

۵. ثبت و پرداخت سفارش
---------------------

[](#۵-ثبت-و-پرداخت-سفارش)

سه endpoint سفارش/خروجی هدر `Idempotency-Key` الزامی دارند. اگر کلید ندهید SDK خودش یک UUID می‌سازد؛ ولی برای retry امن بهتر است کلید را خودتان بسازید و ذخیره کنید تا در تکرار همان کلید ارسال شود.

```
$order = $client->orders()->create($quote->id, idempotencyKey: $myStoredKey);

$order->id;      // ord_...
$order->status;  // pending_payment

$paid = $client->orders()->pay($order->id, idempotencyKey: $myPayKey);

$paid->order->status;               // paid
$paid->order->paidAt;
$paid->wallet->balanceAmount;       // موجودی بعد از کسر
```

پرداخت سفارشِ قبلا پرداخت‌شده خطا نمی‌دهد و وضعیت فعلی را برمی‌گرداند.

۶. خروجی گرفتن (Export)
-----------------------

[](#۶-خروجی-گرفتن-export)

```
use Leadora\Agents\Exports\Export;

$export = $client->orders()->createExport($order->id, Export::FILE_TYPE_CSV);

// ساخت فایل async است؛ وضعیت را poll کنید
$export = $client->exports()->get($export->id);

if ($export->isReady()) {
    $download = $client->exports()->download($export->id);
    // فعلا metadata + message برمی‌گردد؛ لینک دانلود بعدا اضافه می‌شود
}
```

وضعیت‌های export: `pending`، `generating`، `ready`، `failed`، `expired`

خطاها
-----

[](#خطاها)

```
use Leadora\Agents\Exception\ApiException;

try {
    $client->orders()->pay($orderId);
} catch (ApiException $e) {
    $e->errorCode;   // مثلا ApiException::INSUFFICIENT_WALLET_BALANCE
    $e->statusCode;  // مثلا 409
    $e->getMessage();
}
```

کدهای خطای مهم (به‌صورت ثابت روی `ApiException` تعریف شده‌اند):

کدHTTPتوضیح`VALIDATION_ERROR`400ورودی نامعتبر / نبودن Idempotency-Key`UNAUTHORIZED` / `TOKEN_REVOKED` / `TOKEN_EXPIRED`401مشکل توکن`AGENT_DISABLED` / `IP_NOT_ALLOWED` / `SCOPE_NOT_ALLOWED`403دسترسی`USER_NOT_FOUND` / `QUOTE_NOT_FOUND` / `ORDER_NOT_FOUND` / `EXPORT_NOT_FOUND`404یافت نشد`QUOTE_EXPIRED`409پیش‌فاکتور منقضی شده`ORDER_NOT_PAYABLE`409سفارش قابل پرداخت نیست`INSUFFICIENT_WALLET_BALANCE`409موجودی کیف پول کافی نیست`EXPORT_NOT_READY` / `EXPORT_EXPIRED`409خروجی آماده/معتبر نیست`IDEMPOTENCY_CONFLICT`409کلید تکراری با بدنه متفاوت`INTERNAL_ERROR`500خطای داخلی سرورفیلترهای مجاز
-------------

[](#فیلترهای-مجاز)

فقط این فیلدها در `LeadFilter` پشتیبانی می‌شوند:

`province_ids`, `city_ids`, `municipal_district_nos`, `gender`, `age_from`, `age_to`, `birth_year_from`, `birth_year_to`, `mobile_operator_ids`, `mobile_prefixes`, `source_ids`, `batch_ids`

فیلتر روی فیلدهای هویتی و بانکی (نام، کد ملی، شماره کارت و ...) توسط سرور رد می‌شود.

نکته درباره مبالغ
-----------------

[](#نکته-درباره-مبالغ)

همه مبالغ **ریال** و از نوع **int** هستند. هرگز float استفاده نکنید.

تست
---

[](#تست)

```
composer install
./vendor/bin/phpunit
```

###  Health Score

22

—

LowBetter than 21% of packages

Maintenance63

Regular maintenance activity

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/7dc7f2c2da390899357dd3f1f6fae20bc79a8d74912b0a4d586bfcfda3f2e591?d=identicon)[behzad\_azizan](/maintainers/behzad_azizan)

---

Top Contributors

[![behzad-azizan](https://avatars.githubusercontent.com/u/8849640?v=4)](https://github.com/behzad-azizan "behzad-azizan (6 commits)")

### Embed Badge

![Health badge](/badges/leadora-agents-api/health.svg)

```
[![Health](https://phpackages.com/badges/leadora-agents-api/health.svg)](https://phpackages.com/packages/leadora-agents-api)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k18](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)