amirrajabzadeh/farapayamak-laravel

Official Farapayamak SOAP package for Laravel - Full 8 web services with OTP support

v2.1.1 2026-04-16 07:43 UTC

Requires

• php: ^7.4|^8.0|^8.1|^8.2|^8.3|^8.4
• ext-json: *
• ext-soap: *
• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0

MIT

• Amir Rajabzadeh

README

پکیج رسمی و کامل وب سرویس فراپیامک (ملی پیامک) برای لاراول

نویسنده: امیر رجب زاده
ایمیل: [e-mail]
وبسایت: https://amirrajabzadeh.ir
گیت‌هاب: amirrajabzadeh/farapayamak-laravel

✨ ویژگی‌ها

• ✅ پشتیبانی از تمام 8 وب سرویس فراپیامک
• ✅ متد SendOtp برای ارسال کد تأیید یکبارمصرف
• ✅ اضافه شدن خودکار "لغو11" به انتهای پیام (الزامی برای وب سرویس)
• ✅ ارسال پیامک ساده، پیشرفته، چندتایی و زماندار
• ✅ مدیریت کامل دفترچه تلفن و گروه‌ها
• ✅ دریافت پیامک‌های رسیده از صندوق ورودی
• ✅ دریافت اعتبار و وضعیت تحویل پیامک
• ✅ خروجی آرایه استاندارد با ساختار یکسان برای همه متدها
• ✅ بدون نیاز به دیتابیس
• ✅ کامنت‌گذاری کامل به فارسی
• ✅ پشتیبانی از لاراول 8 تا 12
• ✅ پشتیبانی از PHP 7.4 تا 8.4

📋 نیازمندی‌ها

• PHP نسخه 7.4 یا بالاتر (تا 8.4)
• لاراول نسخه 8.x، 9.x، 10.x، 11.x یا 12.x
• افزونه‌های PHP:
  • ext-soap (برای ارتباط با وب سرویس SOAP)
  • ext-json (برای پردازش JSON)

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

📦 نصب

composer require amirrajabzadeh/farapayamak-laravel

⚙️ تنظیمات

1. افزودن متغیرهای محیطی در فایل .env

FARAPAYAMAK_USERNAME=نام_کاربری_شما
FARAPAYAMAK_PASSWORD=رمز_عبور_شما
FARAPAYAMAK_DEBUG=false

2. انتشار فایل کانفیگ (اختیاری)

php artisan vendor:publish --tag=farapayamak-config

فایل کانفیگ در config/farapayamak.php قرار می‌گیرد.

🚀 راهنمای استفاده

ساختار خروجی استاندارد

تمامی متدهای این پکیج یک آرایه استاندارد با ساختار زیر برمی‌گردانند:

[
    'success' => true,      // boolean: موفقیت یا خطا
    'message' => '...',     // string: پیام توضیحی فارسی
    'data' => mixed,        // mixed: داده اصلی (RecId, Credit, ...)
    'code' => null,         // int|null: کد خطا (در صورت موفقیت null)
    'raw' => mixed          // mixed: پاسخ خام وب سرویس (برای دیباگ)
]

1. ارسال پیامک ساده

<?php

namespace App\Http\Controllers;

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamak;

class SmsController extends Controller
{
    public function sendSms()
    {
        $result = FaraPayamak::sendSimpleSms(
            '09130908908',    // شماره گیرنده
            '5000xxxx',       // شماره فرستنده (ثبت شده در پنل)
            'سلام! این یک پیام آزمایشی است.'  // متن پیام (لغو11 خودکار اضافه می‌شود)
        );

        if ($result['success']) {
            return "✅ " . $result['message'] . " - RecId: " . $result['data'];
        }
        
        return "❌ خطا: " . $result['message'] . " (کد: " . $result['code'] . ")";
    }
}

2. ارسال OTP (کد تأیید)

<?php

namespace App\Http\Controllers;

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamak;
use Illuminate\Http\Request;

class OtpController extends Controller
{
    public function sendOtp(Request $request)
    {
        $request->validate([
            'mobile' => 'required|string|size:11',
            'code' => 'required|integer|digits:4|digits:6'
        ]);

        $result = FaraPayamak::sendOtp(
            $request->mobile,          // شماره گیرنده
            '',                        // شماره فرستنده (اختیاری)
            (int)$request->code        // کد عددی 4 یا 6 رقمی
        );

        if ($result['success']) {
            return response()->json([
                'success' => true,
                'message' => $result['message']
            ]);
        }

        return response()->json([
            'success' => false,
            'error' => $result['message']
        ], 500);
    }
}

3. دریافت اعتبار

$result = FaraPayamak::getCredit();

if ($result['success']) {
    echo $result['message'];  // "اعتبار شما 10,270 ریال است"
    echo "مبلغ: " . $result['data'];  // 10270.95
}

4. دریافت وضعیت تحویل پیامک

$result = FaraPayamak::getDeliveryStatus($recId);

if ($result['success']) {
    echo "وضعیت: " . $result['message'];  // "رسیده به گوشی"
    echo "کد: " . $result['data'];  // 1
}

5. دریافت پیامک‌های رسیده

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamakReceive;

// دریافت 50 پیامک آخر
$result = FaraPayamakReceive::getInboxMessages(1, 50);

if ($result['success']) {
    $messages = $result['data'];
    foreach ($messages as $message) {
        echo $message['text'];
    }
}

6. مدیریت دفترچه تلفن

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamakContacts;

// دریافت لیست گروه‌ها
$result = FaraPayamakContacts::getGroups();

if ($result['success']) {
    $groups = $result['data'];
}

// اضافه کردن گروه جدید
$result = FaraPayamakContacts::addGroup('مشتریان ویژه', 'گروه تست');

7. ارسال زماندار

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamakSchedule;

$result = FaraPayamakSchedule::addSchedule(
    '09130908908',                    // شماره گیرنده
    '5000xxxx',                       // شماره فرستنده
    'پیامک زماندار',                   // متن
    false,                            // فلش
    '2024-12-25 14:30:00',           // تاریخ و زمان ارسال
    0                                 // دوره تکرار (0=بدون تکرار)
);

if ($result['success']) {
    echo "زمانبندی با موفقیت انجام شد. شناسه: " . $result['data'];
}

🔧 تزریق مستقیم (بدون Facade)

<?php

namespace App\Http\Controllers;

use Amirrajabzadeh\FarapayamakLaravel\Services\SendService;

class SmsController extends Controller
{
    protected $sendService;

    public function __construct(SendService $sendService)
    {
        $this->sendService = $sendService;
    }

    public function send()
    {
        $result = $this->sendService->sendSimpleSms(
            '09130908908',
            '5000xxxx',
            'متن پیامک'
        );
        
        return $result;
    }
}

📚 سایر سرویس‌ها

پکیج شامل 8 سرویس مجزا است:

Facade	سرویس	توضیحات
FaraPayamak یا FaraPayamakSend	Send	ارسال پیامک، OTP، دریافت اعتبار
FaraPayamakReceive	Receive	دریافت پیامک‌های رسیده
FaraPayamakContacts	Contacts	مدیریت دفترچه تلفن
FaraPayamakSchedule	Schedule	ارسال زماندار
FaraPayamakActions	Actions	ارسال انبوه (Bulk)
FaraPayamakVoice	Voice	پیامک صوتی
FaraPayamakUsers	Users	مدیریت کاربران
FaraPayamakTickets	Tickets	مدیریت تیکت‌ها

⚠️ کدهای خطا

کد	توضیحات
>1000	موفقیت آمیز (RecId - شناسه پیامک)
0	نام کاربری یا رمز عبور اشتباه است
1	درخواست با موفقیت انجام شد (بدون RecId)
2	اعتبار کافی نیست
3	محدودیت ارسال روزانه
4	محدودیت حجم ارسال
5	شماره فرستنده نامعتبر
6	سامانه در حال بروزرسانی
7	متن حاوی کلمات فیلتر شده
14	شماره گیرنده ای یافت نشد
15	متن پیامک خالی است
16	شماره موبایل معتبر نیست

🔧 عیب‌یابی

خطا: Class 'SoapClient' not found

راه حل: افزونه SOAP را در PHP فعال کنید:

; در فایل php.ini
extension=soap

خطا: شماره فرستنده معتبر نیست (کد 5)

راه حل: شماره فرستنده باید یکی از شماره‌های ثبت شده در پنل فراپیامک باشد.

خطا: متن حاوی کلمات فیلتر شده (کد 7)

راه حل: متن پیامک خود را بررسی کنید. همچنین به صورت خودکار "لغو11" به انتهای پیام اضافه می‌شود.

📞 پشتیبانی

• ایمیل: [e-mail]
• وبسایت: https://amirrajabzadeh.ir
• گیت‌هاب: https://github.com/amirrajabzadeh/farapayamak-laravel
• گزارش باگ: Issues

📄 لایسنس

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

ساخته شده با ❤️ توسط امیر رجب زاده