README

A Laravel package specifically designed for Tara360 in-person purchase integration - handles credit payments for physical stores and POS terminals

Installation • Configuration • Usage • [API Reference](#$verifyResult = $tara->purchaseVerify($traceNumber);


## ⚠️ مشکلات معمول و$verifyResult = $tara->purchaseVerify($traceNumber);
```

## 🔍 مدیریت خطاهای بهبود یافته

سرویس حالا **فرمت استاندارد** برای خطاها ارائه می‌دهد:

```php
// فرمت جدید خطاها:
'error' => [
    'title' => 'عنوان خطا',
    'code' => 84780028,
    'message' => 'پیام کاربرپسند'
]
```

### مثال استفاده:

```php
try {
    $result = $tara->purchaseRequest($amount, $payerIdentity);

    if (isset($result['error'])) {
        $error = $result['error'];

        echo "خطا: " . $error['title'] . "\n";
        echo "کد: " . $error['code'] . "\n";
        echo "پیام: " . $error['message'] . "\n";

        // مدیریت خطاهای خاص
        switch ($error['code']) {
            case 84780028:
                echo "راهکار: موجودی حساب را بررسی کنید\n";
                break;
            case 84780001:
                echo "راهکار: اطلاعات کاربری را بررسی کنید\n";
                break;
            default:
                echo "راهکار: لطفاً دوباره تلاش کنید\n";
        }
    }

} catch (TaraException $e) {
    echo "خطای سیستمی: " . $e->getMessage();
}
```

### کدهای خطای رایج:

| کد | معنی | راهکار |
|---|------|---------|
| `84780028` | موجودی کافی نیست | بررسی موجودی حساب |
| `84780001` | اطلاعات کاربری نامعتبر | بررسی نام کاربری و رمز عبور |
| `84780002` | مبلغ تراکنش نامعتبر | بررسی مبلغ وارد شده |
| `84780003` | تراکنش تکراری | بررسی تراکنش‌های قبلی |
| `84780004` | خطا در اتصال | بررسی اتصال شبکه |
```

### کدهای خطای رایج

| کد خطا | پیام فارسی | توضیحات |
|--------|------------|---------|
| 84780028 | موجودی کافی نیست | موجودی کافی برای انجام تراکنش |
| 84780001 | کاربر یافت نشد | کاربر با این مشخصات وجود ندارد |
| 84780015 | ترمینال غیرفعال | ترمینال انتخاب شده فعال نیست |

**مثال response خطا:**
```json
{
  "success": false,
  "error": "موجودی کافی نیست.",
  "error_code": 84780028,
  "error_message": "موجودی کافی نیست.",
  "status": 400,
  "full_response": {
    "data": {"code": 84780028, "message": "موجودی کافی نیست."},
    "success": false,
    "timestamp": "2025-10-01T13:40:48.832853676Z"
  }
}
```

## 📚 منابع و مستندات‌حل‌ها

### مشکل: `purchaseData` تعریف نشده

**خطای معمول:**
```php
// ❌ اشتباه - purchaseData وجود ندارد
$result = $tara->completePurchaseFlow($payment, $purchaseData, $terminalCode);

راه‌حل صحیح:

// ✅ درست - ساخت purchaseData کامل
$item = $tara->createPurchaseItem('نام محصول', 'کد', 1, TaraConstants::UNIT_PIECE, 100000, 'گروه', 'عنوان', TaraConstants::MADE_IRANIAN);
$invoiceData = $tara->createInvoiceData(100000, 'INV001', '', 9000, [$item]);
$purchaseData = $tara->createPurchaseRequestData(100000, 'INV001', '', [$invoiceData]);
$result = $tara->completePurchaseFlow($payment, $purchaseData, $terminalCode);

مثال کامل بدون خطا: TaraExampleFixed.php

📚 منابع و مستنداتreference) • فارسی

About Tara360

Tara360 is Iran's leading credit payment and digital wallet application that enables customers to make purchases on credit and pay in installments. With over 14,000+ merchant partners across Iran, Tara360 provides:

� Specialized for In-Person Purchases

Physical Store Integration: Designed specifically for brick-and-mortar stores
POS Terminal Support: Works with Tara360 POS terminals and cash registers
Branch & Terminal Management: Handle multiple store locations and terminals
Real-time Transaction Processing: Immediate payment processing for in-store purchases

💳 Credit Amounts

Micro Credit: 500,000 to 10,000,000 IRR
Quick Loan: Additional loan facilities for approved users
Organization Services: Corporate credit solutions

🏆 Awards & Recognition

Winner of FAB Silver Award in IT Product Excellence at the 8th National IT Awards
Trusted by thousands of merchants and millions of customers

Note: This package is specifically designed for in-person purchases at physical stores using Tara360 POS terminals. For online purchases or other Tara services, please check our other packages.

Installation

Option 1: Install from Packagist (Recommended)

composer require shahkochaki/tara-in-person-purchases

Option 2: Install from GitHub (If Packagist is not available)

Add to your composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/shahkochaki/tara-in-person-purchases.git"
    }
  ],
  "require": {
    "shahkochaki/tara-in-person-purchases": "^1.0"
  }
}

Then run:

composer install

Configuration

Quick Setup (Recommended)

1. Copy configuration files directly:

File	Description	Quick Copy
`.env` setup	Environment variables	📋 Copy .env template
Config file	Laravel configuration	📋 Copy config/tara.php

2. One-command setup:

# Copy .env template
curl -o .env.tara https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/.env.example

# Copy config file (Laravel)
curl -o config/tara.php https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/config/tara.php

Manual Setup

Publish the config file (Laravel):

php artisan vendor:publish --provider="Shahkochaki\TaraService\TaraServiceProvider"

Add your Tara credentials to .env:

# Tara API Configuration
TARA_BASE_URL=https://stage.tara-club.ir/club/api/v1
TARA_USERNAME=your_username_here
TARA_PASSWORD=your_password_here
TARA_BRANCH_CODE=your_branch_code_here
TARA_LOGGING=true

⚠️ Security Note: Never commit your actual credentials to version control. Replace the placeholder values with your real Tara API credentials.

Configuration Options

📚 Detailed Configuration Guide: CONFIG_GUIDE.md

Setting	Description	Default
`TARA_BASE_URL`	API base URL	`https://stage.tara-club.ir/club/api/v1`
`TARA_USERNAME`	Your Tara username	Required
`TARA_PASSWORD`	Your Tara password	Required
`TARA_BRANCH_CODE`	Your branch code	Required
`TARA_ENVIRONMENT`	Environment (staging/production)	`staging`
`TARA_TOKEN_BUFFER`	Token expiry buffer (seconds)	`60`
`TARA_LOGGING_ENABLED`	Enable logging	`true`

Environment-Specific Configuration

# Development/Staging
TARA_BASE_URL=https://stage.tara-club.ir/club/api/v1
TARA_ENVIRONMENT=staging

# Production
TARA_BASE_URL=https://api.tara-club.ir/club/api/v1
TARA_ENVIRONMENT=production

Usage

Basic Implementation

use Shahkochaki\TaraService\TaraService;
use Shahkochaki\TaraService\TaraConstants;

// Create instance (reads config automatically)
$tara = new TaraService();

// Or with specific branch code
$tara = new TaraService('your_branch_code');

// Or with custom configuration
$config = [
    'credentials' => [
        'username' => 'your_username',
        'password' => 'your_password'
    ],
    'default_branch_code' => 'your_branch_code'
];
$tara = new TaraService('your_branch_code', $config);

📖 Complete Setup Guide: SETUP_GUIDE.md

Quick Start (One Method)

try {
    $tara = new TaraService();

    // Customer barcode (one-time use from customer)
    $customerBarcode = 9700083615425377;
    $amount = 100000; // 100,000 IRR

    // Payment data
    $payment = [$tara->createTracePayment($customerBarcode, $amount, 0)];

    // Purchase items
    $items = [
        $tara->createPurchaseItem('نان سنگک', '12345', 2.0, 5, 50000, 'BAKERY', 'نانوایی', 1)
    ];

    $invoiceData = $tara->createInvoiceData($amount, 'INV-' . time(), 'Purchase', 9000, $items);
    $purchaseData = $tara->createPurchaseRequestData($amount, 'INV-' . time(), 'Test', $invoiceData);

    // Complete flow: login → terminals → trace → request → verify
    $result = $tara->completePurchaseFlow($payment, $purchaseData);

    if ($result['success']) {
        echo "Purchase successful! Trace: " . $result['traceNumber'];
    } else {
        echo "Purchase failed: " . $result['error'];
    }

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
    echo "\nPlease ensure credentials are set in .env file";
}

Step-by-Step Implementation

try {
    // 1. Initialize session (login + get terminals)
    $tara = new TaraService();
    $sessionResult = $tara->initializeSession();

    if (!$sessionResult['success']) {
        throw new Exception('Session failed: ' . $sessionResult['error']);
    }

    // 2. Select terminal (optional - uses first terminal if not selected)
    $terminals = $tara->getTerminals();
    $terminalCode = $terminals[0]['terminalCode'];
    $tara->selectTerminal($terminalCode);

    // 3. Create payment trace for customer
    $customerBarcode = 9700083615425377; // From customer (one-time use)
    $amount = 500000; // Amount in IRR (Rials)

    $payment = [
        $tara->createTracePayment($customerBarcode, $amount, 0)
    ];

    $traceResult = $tara->purchaseTrace($payment, $terminalCode);

    if (!$traceResult['success']) {
        throw new Exception('Trace failed: ' . $traceResult['error']);
    }

    $traceNumber = $traceResult['data']['traceNumber'];

    // 4. Create purchase items and invoice
    $item = $tara->createPurchaseItem(
        'Premium Product',           // Product name
        'PROD001',                  // Product code
        TaraConstants::UNIT_PIECE,  // Unit type
        2,                          // Quantity
        250000,                     // Unit price (IRR)
        'ELECTRONICS',              // Group code
        'Electronics',              // Group name
        TaraConstants::MADE_FOREIGN // Origin
    );

    $invoice = $tara->createInvoiceData(
        $amount,      // Total amount
        'INV-2025001', // Invoice number
        'Purchase description',
        0,            // Discount
        [$item]       // Items array
    );

    $purchaseData = $tara->createPurchaseRequestData(
        $amount,       // Total amount
        'INV-2025001', // Invoice number
        'Purchase via Tara API',
        [$invoice]     // Invoices array
    );

    // 5. Submit purchase request
    $requestResult = $tara->purchaseRequest($purchaseData, $traceNumber);

    if (!$requestResult['success']) {
        throw new Exception('Purchase request failed: ' . $requestResult['error']);
    }

    // 6. Verify purchase
    $verifyResult = $tara->purchaseVerify($traceNumber);

    if ($verifyResult['success']) {
        echo "Purchase completed successfully!";
        // Process successful payment
    } else {
        echo "Purchase verification failed: " . $verifyResult['error'];
        // Handle failed verification
    }

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
    // Handle errors appropriately
}

API Reference

Core Methods

Authentication

$result = $tara->login();
// Returns: ['success' => bool, 'data' => array, 'error' => string]

Terminal Management

$result = $tara->getAccessCode($branchCode = null);
$terminals = $tara->getAvailableTerminals($accessCodeResult);
$terminalCode = $tara->getTerminalCodeFromResponse($accessCodeResult, $index);

Product Categories

$result = $tara->getMerchandiseGroups();

Purchase Flow

// Create payment trace
$result = $tara->purchaseTrace($paymentArray, $terminalCode);

// Submit purchase request (with terminal code - optional)
$result = $tara->purchaseRequest($purchaseData, $traceNumber, $terminalCode);

// Verify purchase (with terminal code - optional)
$result = $tara->purchaseVerify($traceNumber, $terminalCode);

// Reverse/cancel purchase (with terminal code - optional)
$result = $tara->purchaseReverse($traceNumber, $terminalCode);

// Inquiry purchase status (with terminal code - optional)
$result = $tara->purchaseInquiry($referenceOrTraceNumber, $terminalCode);

Important Note: All purchase operations (purchaseRequest, purchaseVerify, purchaseReverse, purchaseInquiry) now use terminal tokens instead of user tokens for better security and API compliance. Terminal code is optional - if not provided, the service will use the selected terminal or first available terminal.


### Helper Methods

```php
// Create payment data for trace
$payment = $tara->createTracePayment($userId, $amount, $discount);

// Create purchase item
$item = $tara->createPurchaseItem($name, $code, $unit, $quantity, $price, $groupCode, $groupName, $madeIn);

// Create invoice data
$invoice = $tara->createInvoiceData($totalAmount, $invoiceNumber, $description, $discount, $items);

// Create complete purchase request data
$purchaseData = $tara->createPurchaseRequestData($totalAmount, $invoiceNumber, $description, $invoices);

Constants

// Product Units
TaraConstants::UNIT_PIECE        // 5 - Piece
TaraConstants::UNIT_KILOGRAM     // 1 - Kilogram
TaraConstants::UNIT_METER        // 2 - Meter
TaraConstants::UNIT_LITER        // 3 - Liter
TaraConstants::UNIT_GRAM         // 4 - Gram

// Product Origin
TaraConstants::MADE_IRANIAN      // 1 - Made in Iran
TaraConstants::MADE_FOREIGN      // 2 - Foreign made
TaraConstants::MADE_UNKNOWN      // 0 - Unknown origin

Response Format

All methods return a standardized response array:

// Success Response
[
    'success' => true,
    'data' => [],              // Response data on success
]

// Error Response (Enhanced)
[
    'success' => false,        // Operation success status
    'error' => '',             // Main error message
    'error_code' => 84780028,  // API error code (if available)
    'error_message' => 'موجودی کافی نیست.',  // Detailed error message
    'error_data' => [],        // Full error data from API
    'status' => 400,           // HTTP status code
    'full_response' => [],     // Complete API response for debugging
]

Enhanced Error Handling

The service now provides detailed error information including error codes and Persian error messages from the Tara API:

try {
    $result = $tara->purchaseRequest($data, $traceNumber);

    if (!$result['success']) {
        // Display main error message
        echo "Error: " . $result['error'] . "\n";

        // Display error code if available
        if (isset($result['error_code'])) {
            echo "Error Code: " . $result['error_code'] . "\n";
        }

        // Display detailed error message
        if (isset($result['error_message'])) {
            echo "Details: " . $result['error_message'] . "\n";
        }

        // Full error data for debugging
        if (isset($result['error_data'])) {
            var_dump($result['error_data']);
        }
    }

} catch (Exception $e) {
    echo "System Error: " . $e->getMessage();
}

Common Error Codes

Error Code	Persian Message	English Description
84780028	موجودی کافی نیست	Insufficient balance
84780001	کاربر یافت نشد	User not found
84780015	ترمینال غیرفعال	Terminal inactive

Legacy Error Handling

use Shahkochaki\TaraService\TaraException;

try {
    $result = $tara->purchaseRequest($data, $traceNumber);

    if (!$result['success']) {
        // Handle API errors
        Log::error('Tara API Error: ' . $result['error']);
        throw new TaraException($result['error']);
    }

} catch (TaraException $e) {
    // Handle Tara-specific exceptions
    return response()->json(['error' => $e->getMessage()], 400);
} catch (Exception $e) {
    // Handle general exceptions
    return response()->json(['error' => 'Payment processing failed'], 500);
}

Testing

# Run tests
composer test

# Or with PHPUnit directly
./vendor/bin/phpunit

Requirements

PHP: >= 7.4
Laravel: >= 8.0
Extensions: cURL, JSON

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Security

If you discover any security vulnerabilities, please email [ali.shahkochaki7@gmail.com] instead of using the issue tracker.

Changelog

See CHANGELOG.md for detailed changes.

License

The MIT License (MIT). Please see License File for more information.

Support

Phone: 1573 (7 days a week, 24 hours)
Website: https://tara360.ir
Documentation: https://tara360.ir/faq

فارسی

درباره تارا۳۶۰

تارا۳۶۰ یکی از پیشروترین اپلیکیشن‌های پرداخت اعتباری و کیف پول دیجیتال ایران است که به مشتریان امکان خرید اعتباری و پرداخت قسطی را می‌دهد. با بیش از ۱۴,۰۰۰ فروشگاه شریک در سراسر ایران، تارا۳۶۰ خدماتی شامل:

✨ ویژگی‌های کلیدی

خرید اعتباری: الان بخر، بعداً در ۲-۳ قسط پرداخت کن
کیف پول دیجیتال: کیف پول نقدی با ۳٪ بازگشت پول
بدون ضامن: تأیید آنی اعتبار بدون نیاز به ضامن
تأیید فوری: دریافت اعتبار در کمتر از ۲۰ دقیقه
شبکه گسترده: ۱۴,۰۰۰+ فروشگاه و مرکز خدماتی در سراسر کشور
آنلاین و حضوری: پشتیبانی از خرید آنلاین و حضوری

💰 میزان اعتبار

اعتبار خرد: ۵۰۰,۰۰۰ تا ۱۰,۰۰۰,۰۰۰ تومان
وام فوری: امکانات وام اضافی برای کاربران تأیید شده
خدمات سازمانی: راهکارهای اعتباری سازمانی

نصب

composer require shahkochaki/tara-in-person-purchases

تنظیمات

۱. انتشار فایل تنظیمات:

php artisan vendor:publish --provider="Shahkochaki\TaraService\TaraServiceProvider"

۲. اضافه کردن اطلاعات تارا به .env:

TARA_BASE_URL=https://stage.tara-club.ir/club/api/v1
TARA_USERNAME=نام_کاربری_شما
TARA_PASSWORD=رمز_عبور_شما
TARA_BRANCH_CODE=کد_شعبه_شما

استفاده

پیاده‌سازی ساده

use Shahkochaki\TaraService\TaraService;
use Shahkochaki\TaraService\TaraConstants;

// استفاده از dependency injection (توصیه شده)
$tara = app(TaraService::class);

// یا ایجاد دستی
$tara = new TaraService('کد_شعبه', 'نام_کاربری', 'رمز_عبور');

فرآیند کامل خرید

// ۱. ورود به سیستم (خودکار با اولین فراخوانی API)
$loginResult = $tara->login();

// ۲. دریافت کد دسترسی و انتخاب ترمینال
$accessCodeResult = $tara->getAccessCode();
$terminalCode = $tara->getTerminalCodeFromResponse($accessCodeResult, 0);

// ۳. ایجاد ردیابی پرداخت
$userId = ۱۲۳۴۵۶۷۸۹۰; // شناسه کاربری مشتری
$amount = ۵۰۰۰۰۰; // مبلغ به ریال

$payment = [
    $tara->createTracePayment($userId, $amount, 0)
];

$traceResult = $tara->purchaseTrace($payment, $terminalCode);
$traceNumber = $traceResult['data']['traceNumber'];

// ۴. ایجاد آیتم خرید و فاکتور
$item = $tara->createPurchaseItem(
    'محصول پریمیم',                // نام محصول
    'PROD001',                  // کد محصول
    ۲,                          // تعداد
    TaraConstants::UNIT_PIECE,  // نوع واحد
    ۲۵۰۰۰۰,                     // قیمت واحد (ریال)
    'ELECTRONICS',              // کد گروه
    'الکترونیک',                // نام گروه
    TaraConstants::MADE_FOREIGN // منشأ
);

// ۵. ایجاد اطلاعات فاکتور
$invoiceData = $tara->createInvoiceData(
    ۵۰۰۰۰۰,                     // مبلغ کل
    'INV' . time(),            // شماره فاکتور
    '',                        // اطلاعات اضافی
    ۴۵۰۰۰,                     // مالیات (۹%)
    [$item]                    // آیتم‌های خرید
);

// ۶. ایجاد درخواست خرید (purchaseData)
$purchaseData = $tara->createPurchaseRequestData(
    ۵۰۰۰۰۰,                    // مبلغ
    'INV' . time(),           // شماره فاکتور
    '',                       // اطلاعات اضافی
    [$invoiceData]            // اطلاعات فاکتور
);

// ۷. ارسال درخواست خرید
$requestResult = $tara->purchaseRequest($purchaseData, $traceNumber);

// ۸. تأیید خرید
$verifyResult = $tara->purchaseVerify($traceNumber);

� منابع و مستندات

فایل‌های پیکربندی

نوع فایل	توضیحات	لینک مستقیم برای کپی
`.env`	متغیرهای محیطی	کپی فایل .env
`config/tara.php`	پیکربندی Laravel	کپی فایل config

راهنماهای تخصصی

موضوع	توضیحات	فایل
نصب و راه‌اندازی	راهنمای گام به گام نصب	SETUP_GUIDE.md
پیکربندی سیستم	تنظیمات پیشرفته	CONFIG_GUIDE.md
جریان کاری API	توضیح کامل فرآیند	API_FLOW_GUIDE.md

دستورات سریع برای شروع

# کپی فایل پیکربندی محیطی
curl -o .env https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/.env.example

# کپی فایل پیکربندی Laravel (اختیاری)
mkdir -p config
curl -o config/tara.php https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/config/tara.php

نمونه کدهای عملی

نوع کد	توضیحات	فایل
استفاده ساده	مثال کلی از سرویس	TaraExample.php
پیکربندی محیطی	استفاده از env variables	TaraExampleUpdated.php
پیکربندی پیشرفته	استفاده از config arrays	TaraConfigExample.php
کد اصلاح شده	رفع مشکل purchaseData	TaraExampleFixed.php
مدیریت خطا	نمایش کد و پیام خطا	TaraErrorHandlingExample.php
پیکربندی پیشرفته	استفاده از config arrays	TaraConfigExample.php

�📄 مستندات کامل فارسی

برای راهنمای کامل و مستندات فارسی، فایل زیر را مشاهده کنید:

دانلود مستندات فارسی (Persian-document.pdf)

پشتیبانی

تلفن: ۱۵۷۳ (۷ روز هفته، ۲۴ ساعته)
وب‌سایت: https://tara360.ir
سوالات متداول: https://tara360.ir/faq

مجوز

مجوز MIT. برای اطلاعات بیشتر فایل مجوز را مشاهده کنید.

shahkochaki / tara-in-person-purchases

Maintainers

Details

README

📚 منابع و مستنداتreference) • فارسی

About Tara360

� Specialized for In-Person Purchases

💳 Credit Amounts

🏆 Awards & Recognition

Installation

Option 1: Install from Packagist (Recommended)

Option 2: Install from GitHub (If Packagist is not available)

Configuration

Quick Setup (Recommended)

Manual Setup

Configuration Options

Environment-Specific Configuration

Usage

Usage

Basic Implementation

Quick Start (One Method)

Step-by-Step Implementation

API Reference

Core Methods

Authentication

Terminal Management

Product Categories

Purchase Flow

Constants

Response Format

Enhanced Error Handling

Common Error Codes

Legacy Error Handling

Testing

Requirements

Contributing

Security

Changelog

License

Support

فارسی

درباره تارا۳۶۰

✨ ویژگی‌های کلیدی

💰 میزان اعتبار

نصب

تنظیمات

استفاده

پیاده‌سازی ساده

فرآیند کامل خرید

� منابع و مستندات

فایل‌های پیکربندی

راهنماهای تخصصی

دستورات سریع برای شروع

نمونه کدهای عملی

�📄 مستندات کامل فارسی

پشتیبانی

مجوز