☰
راهنمای توسعه‌دهندگان (API)
☀️
پیشخوان / مستندات API

مستندات API توسعه‌دهندگان

راهنمای اتصال نرم‌افزارها و وب‌سایت‌ها به پلتفرم ثبت فاکتور سامانه مودیان.

🚀
شروع کار

برای شروع ارتباط با API، ابتدا باید از پنل اتصال به سایت (API) یک توکن دسترسی (Bearer Token) بسازید. این توکن باید در هدر (Header) تمامی درخواست‌های شما گنجانده شود. آدرس پایه تمامی درخواست‌ها: https://sabtfaktor.ir/api

POST
ثبت فاکتور جدید

این متد برای ایجاد و ذخیره یک فاکتور جدید (به عنوان پیش‌نویس) استفاده می‌شود. پس از ایجاد فاکتور، یک واحد از محدودیت پلن کاربر کسر می‌گردد.

POST /v1/invoices

هدرهای مورد نیاز (Headers)

Key Value
Authorization Bearer {YOUR_API_TOKEN}
Content-Type application/json
Accept application/json

نمونه درخواست (Request Body)

بدنه درخواست باید شامل payload باشد که دقیقاً طبق استاندارد سامانه مودیان به صورت header و body ساختاربندی شده است.

پارامترهای مهم هدر (Header)

  • inp: الگوی صورتحساب (۱: فروش معمولی، ۳: طلا و جواهر، ۴: قرارداد پیمانکاری)
  • setm: روش تسویه (۱: نقدی، ۲: نسیه، ۳: نقدی/نسیه)
  • cap: مبلغ پرداختی نقدی (فقط در صورتی که روش تسویه ۳ باشد)
  • crn: شماره قرارداد پیمانکاری (فقط برای الگوی ۴ - حداکثر ۱۲ کاراکتر عددی)

پارامترهای مهم بدنه (Body) - مخصوص الگوی طلا (۳)

  • consfee: اجرت ساخت
  • spro: سود فروشنده
  • bros: حق‌العمل
  • cui: عیار طلا
{
  "payload": {
    "header": {
      "uid": "123e4567-e89b-12d3-a456-426614174000",
      "indatim": "2025-08-18",
      "inty": 1,
      "inp": 3,
      "ins": 1,
      "tob": 1,
      "tinb": "1234567890",
      "buyer_type": "real",
      "buyer_name": "علی محمدی",
      "tprdis": 1000000,
      "tdis": 0,
      "tadis": 1000000,
      "tvam": 90000,
      "tbill": 1090000,
      "setm": 3,
      "cap": 500000
    },
    "body": [
      {
        "sstid": "2720000114532",
        "sstt": "دستبند طلا",
        "am": 1,
        "fee": 1000000,
        "prdis": 1000000,
        "dis": 0,
        "adis": 1000000,
        "consfee": 50000,
        "spro": 20000,
        "bros": 10000,
        "cui": 750,
        "vra": 9,
        "vam": 90000,
        "tsstam": 1090000
      }
    ],
    "payments": [
      { "pmt": 1 }
    ]
  }
}

نمونه پاسخ (Response) - موفق 201

{
  "success": true,
  "message": "Invoice saved as draft successfully.",
  "data": {
    "invoice_id": 42,
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "draft"
  }
}

نمونه پاسخ (Response) - خطا 403 (اتمام پلن)

{
  "success": false,
  "message": "Your subscription limit has been reached or your package is expired. Please renew your package."
}

نمونه کد با PHP (cURL)

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://sabtfaktor.ir/api/v1/invoices',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "payload": { ... }
  }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer YOUR_API_TOKEN'
  ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

🔍
استعلام وضعیت فاکتور

با این متد می‌توانید از طریق شناسه (uid) فاکتوری که قبلا ارسال کرده‌اید، وضعیت نهایی آن را از سامانه مودیان استعلام بگیرید.

GET /v1/invoices/{uid}/status

نمونه پاسخ (Response)

{
  "success": true,
  "data": {
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "success",
    "reference_id": "1234567890123456789012",
    "taxid": "1234567890123456789012",
    "error_message": null
  }
}

📦
وضعیت بسته و فاکتورهای مانده

این متد اطلاعات بسته فعال شما، تعداد کل فاکتورهای مجاز و تعداد فاکتورهای باقی‌مانده را برمی‌گرداند.

GET /v1/package/status

نمونه پاسخ (Response)

{
  "success": true,
  "data": {
    "has_active_package": true,
    "package_name": "بسته حرفه‌ای",
    "invoice_limit": 1000,
    "invoices_used": 150,
    "invoices_remaining": 850,
    "starts_at": "2025-01-01 00:00:00",
    "ends_at": "2026-01-01 00:00:00"
  }
}