مستندات API — سامانه تولید فرم PDF

شروع سریع

در چند دقیقه اولین درخواست خود را بزنید.

۱

ثبت‌نام و دریافت توکن

در سامانه ثبت‌نام کنید، به بخش «توکن API» در پروفایل بروید و توکن خود را بسازید.

۲

لیست فرم‌ها را دریافت کنید

با یک درخواست GET، همه فرم‌های فعال و شناسه (id) آن‌ها را بگیرید.

۳

فرم را پر و ارسال کنید

با یک POST، داده‌های کاربر را ارسال کنید. در پاسخ، submission_id و آدرس PDF دریافت می‌کنید.

۴

PDF را دانلود کنید

با pdf_url که در پاسخ دریافت کردید، فایل PDF را مستقیم دریافت کنید.

همه پاسخ‌ها JSON هستند (Content-Type: application/json; charset=utf-8)، به جز endpoint دانلود PDF که فایل باینری برمی‌گرداند.

احراز هویت

تمام endpoint‌ها نیاز به ارسال توکن API دارند. توکن را در هدر Authorization ارسال کنید.

Authorization: Bearer YOUR_API_TOKEN

# توصیه نمی‌شود — برای تست سریع
GET /api/v1/forms?api_token=YOUR_API_TOKEN

توکن را هیچ‌گاه در کد فرانت‌اند (JavaScript سمت کلاینت) قرار ندهید. همیشه درخواست‌ها را از سرور ارسال کنید.

نحوه دریافت توکن API

توکن API شناسه منحصربه‌فرد حساب شما برای دسترسی به API است.

۱

ورود به حساب کاربری

به آدرس /login بروید و وارد شوید.

۲

بخش توکن API

از منوی کاربری، «توکن API» را انتخاب کنید یا مستقیم به /api-token بروید.

۳

ایجاد توکن جدید

روی «ایجاد توکن جدید» کلیک کنید. توکن فقط یک‌بار نمایش داده می‌شود — آن را کپی کنید.

در هر زمان می‌توانید توکن قدیمی را ابطال (revoke) کرده و توکن جدید صادر کنید. پس از ابطال، توکن قدیمی دیگر کار نمی‌کند.

GET /api/v1/me

اطلاعات حساب کاربری متصل به توکن را برمی‌گرداند.

GET https://yoursite.com/api/v1/me

نمونه درخواست

curl -X GET \
  'https://yoursite.com/api/v1/me' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

const res = await fetch('https://yoursite.com/api/v1/me', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const data = await res.json();
console.log(data);

$ch = curl_init('https://yoursite.com/api/v1/me');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_TOKEN'
]);
$response = json_decode(curl_exec($ch), true);

نمونه پاسخ موفق (200)

{
  "ok": true,
  "data": {
    "id":        1,
    "full_name": "علی محمدی",
    "email":    "ali@example.com",
    "role":     "user"
  }
}

GET /api/v1/forms

لیست همه فرم‌های فعال سامانه را برمی‌گرداند.

GET https://yoursite.com/api/v1/forms

نمونه درخواست

curl 'https://yoursite.com/api/v1/forms' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

const { data: forms } = await fetch('https://yoursite.com/api/v1/forms', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
}).then(r => r.json());

$ctx = stream_context_create(['http' => [
    'header' => "Authorization: Bearer YOUR_API_TOKEN\r\n"
]]);
$result = json_decode(file_get_contents(
    'https://yoursite.com/api/v1/forms', false, $ctx
), true);

نمونه پاسخ موفق (200)

{
  "ok": true,
  "data": [
    {
      "id":          1,
      "title":       "فرم ثبت‌نام",
      "slug":        "registration",
      "description": "فرم ثبت‌نام اولیه"
    },
    {
      "id":          2,
      "title":       "فرم استخدام",
      "slug":        "employment",
      "description": "فرم درخواست استخدام"
    }
  ]
}

GET /api/v1/forms/{id}

ساختار کامل یک فرم (صفحه‌ها و فیلدها) را برمی‌گرداند. از این اطلاعات برای رندر کردن فرم در سمت خود استفاده کنید.

GET https://yoursite.com/api/v1/forms/{id}

پارامترهای مسیر

پارامتر	نوع	وضعیت	توضیح
`id`	integer	الزامی	شناسه عددی فرم (از GET /forms به دست می‌آید)

نمونه درخواست

curl 'https://yoursite.com/api/v1/forms/1' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

const { data: form } = await fetch('https://yoursite.com/api/v1/forms/1', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
}).then(r => r.json());

نمونه پاسخ موفق (200)

{
  "ok": true,
  "data": {
    "id":    1,
    "title": "فرم ثبت‌نام",
    "slug":  "registration",
    "pages": [
      {
        "id":     1,
        "title": "اطلاعات شخصی",
        "order": 1,
        "fields": [
          {
            "form_field_id":  1,
            "field_key":     "first_name",
            "label":         "نام",
            "type":          "text",
            "required":      true,
            "validation":   "persian",
            "description":  "نام کوچک فارسی",
            "pdf_field_name":"name_field"
          },
          {
            "form_field_id":  2,
            "field_key":     "national_code",
            "label":         "کد ملی",
            "type":          "text",
            "required":      true,
            "validation":   "national_code"
          }
        ]
      }
    ]
  }
}

POST /api/v1/forms/{id}/submit

داده‌های فرم را ارسال می‌کند. در پاسخ، submission_id و آدرس PDF دریافت می‌کنید.

POST https://yoursite.com/api/v1/forms/{id}/submit

هدر Content-Type: application/json الزامی است. داده‌ها را در بدنه JSON ارسال کنید.

پارامترهای مسیر

پارامتر	نوع	وضعیت	توضیح
`id`	integer	الزامی	شناسه عددی فرم

بدنه درخواست (JSON)

کلید	نوع	وضعیت	توضیح
`{field_key}`	string	بسته به فرم	مقدار هر فیلد با `field_key` آن (از GET /forms/{id})

نمونه درخواست

curl -X POST \
  'https://yoursite.com/api/v1/forms/1/submit' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name":    "علی",
    "last_name":     "محمدی",
    "national_code": "0012345678",
    "mobile":        "09121234567"
  }'

const result = await fetch('https://yoursite.com/api/v1/forms/1/submit', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type':  'application/json'
  },
  body: JSON.stringify({
    first_name:    'علی',
    last_name:     'محمدی',
    national_code: '0012345678',
    mobile:        '09121234567'
  })
}).then(r => r.json());
// result.submission_id → برای دریافت PDF

$data = json_encode([
    'first_name'    => 'علی',
    'last_name'     => 'محمدی',
    'national_code' => '0012345678',
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://yoursite.com/api/v1/forms/1/submit');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $data,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_TOKEN',
        'Content-Type: application/json'
    ]
]);
$result = json_decode(curl_exec($ch), true);

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

{
  "ok":            true,
  "submission_id": 42,
  "message":       "فرم با موفقیت ثبت شد.",
  "pdf_url":       "/api/v1/submissions/42/pdf"
}

نمونه پاسخ خطای اعتبارسنجی (422)

{
  "ok":    false,
  "error": "فیلد الزامی «کد ملی» خالی است."
}

GET /api/v1/submissions/{id}

وضعیت، داده‌ها و لینک PDF یک ارسال را برمی‌گرداند. فقط صاحب ارسال یا مدیر دسترسی دارد.

GET https://yoursite.com/api/v1/submissions/{id}

پارامترهای مسیر

پارامتر	نوع	وضعیت	توضیح
`id`	integer	الزامی	شناسه عددی ارسال (از POST submit دریافت می‌شود)

نمونه درخواست

curl 'https://yoursite.com/api/v1/submissions/42' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

const { data } = await fetch('https://yoursite.com/api/v1/submissions/42', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
}).then(r => r.json());

نمونه پاسخ موفق (200)

{
  "ok": true,
  "data": {
    "id":         42,
    "form_id":    1,
    "status":     "paid",
    "created_at": "2026-05-11 10:30:00",
    "fields": {
      "first_name":    "علی",
      "last_name":     "محمدی",
      "national_code": "0012345678"
    },
    "pdf_url": "/api/v1/submissions/42/pdf"
  }
}

مقادیر وضعیت (status)

مقدار	معنا
`pending_payment`	در انتظار پرداخت
`paid`	پرداخت شده — PDF قابل دریافت است
`cancelled`	لغو شده

GET /api/v1/submissions/{id}/pdf

فایل PDF ارسال را به صورت باینری دانلود می‌کند. پاسخ JSON نیست — مستقیم داده باینری PDF برمی‌گردد.

GET https://yoursite.com/api/v1/submissions/{id}/pdf

پاسخ با هدر Content-Type: application/pdf و Content-Disposition: attachment ارسال می‌شود.

نمونه درخواست

# ذخیره مستقیم روی دیسک
curl -OJ \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  'https://yoursite.com/api/v1/submissions/42/pdf'

const blob = await fetch('https://yoursite.com/api/v1/submissions/42/pdf', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
}).then(r => r.blob());

// دانلود در مرورگر
const url  = URL.createObjectURL(blob);
const link = document.createElement('a');
link.href     = url;
link.download = 'form_42.pdf';
link.click();
URL.revokeObjectURL(url);

$ch = curl_init('https://yoursite.com/api/v1/submissions/42/pdf');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_API_TOKEN']
]);
$pdfData = curl_exec($ch);

// ارسال به مرورگر
header('Content-Type: application/pdf');
header('Content-Disposition: attachment; filename="form_42.pdf"');
echo $pdfData;

کدهای خطا

همه پاسخ‌های خطا دارای ساختار {"ok": false, "error": "..."} هستند.

200

OK — موفق

201

Created — ایجاد شد

400

Bad Request — خطای ورودی

401

Unauthorized — توکن نامعتبر

403

Forbidden — دسترسی مجاز نیست

404

Not Found — یافت نشد

422

Unprocessable — اعتبارسنجی ناموفق

500

Server Error — خطای سرور

{
  "ok":    false,
  "error": "توکن API نامعتبر است یا منقضی شده."
}

محدودیت نرخ (Rate Limiting)

در حال حاضر API محدودیت نرخ سختی ندارد، اما برای عملکرد بهتر موارد زیر را رعایت کنید.

بهترین شیوه‌ها:
— نتیجه GET /forms را کش کنید (تغییرات به‌ندرت رخ می‌دهد)
— برای تولید PDF‌های زیاد، درخواست‌ها را Sequential (نه همزمان) ارسال کنید
— توکن API را هرگز در فرانت‌اند معرض عموم قرار ندهید

مثال کامل — از فرم تا PDF

این مثال کل flow را نشان می‌دهد: دریافت فرم، ارسال، و دانلود PDF.

const TOKEN = 'YOUR_API_TOKEN';
const BASE  = 'https://yoursite.com/api/v1';
const hdrs  = { 'Authorization': `Bearer ${TOKEN}` };

// ── ۱. لیست فرم‌ها ──
const { data: forms } = await fetch(`${BASE}/forms`, { headers: hdrs }).then(r => r.json());
const formId = forms[0].id; // اولین فرم

// ── ۲. ساختار فرم (اختیاری — برای رندر فیلدها) ──
const { data: form } = await fetch(`${BASE}/forms/${formId}`, { headers: hdrs }).then(r => r.json());
console.log('فیلدها:', form.pages[0].fields.map(f => f.field_key));

// ── ۳. ارسال فرم ──
const submit = await fetch(`${BASE}/forms/${formId}/submit`, {
  method: 'POST',
  headers: { ...hdrs, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    first_name:    'علی',
    last_name:     'محمدی',
    national_code: '0012345678',
    mobile:        '09121234567'
  })
}).then(r => r.json());

if (!submit.ok) throw new Error(submit.error);
const { submission_id, pdf_url } = submit;

// ── ۴. دانلود PDF ──
const pdfBlob = await fetch(`${BASE}${pdf_url}`, { headers: hdrs }).then(r => {
  if (!r.ok) throw new Error('خطا در دانلود PDF');
  return r.blob();
});

// ذخیره در مرورگر
const link = document.createElement('a');
link.href     = URL.createObjectURL(pdfBlob);
link.download = `submission_${submission_id}.pdf`;
link.click();

<?php
$TOKEN = 'YOUR_API_TOKEN';
$BASE  = 'https://yoursite.com/api/v1';

function apiGet($url, $token): array {
    $ctx = stream_context_create(['http' => ['header' => "Authorization: Bearer $token\r\n"]]);
    return json_decode(file_get_contents($url, false, $ctx), true);
}

// ── ۱. لیست فرم‌ها ──
$forms  = apiGet("$BASE/forms", $TOKEN)['data'];
$formId = $forms[0]['id'];

// ── ۲. ارسال فرم ──
$ch = curl_init("$BASE/forms/$formId/submit");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'first_name'    => 'علی',
        'last_name'     => 'محمدی',
        'national_code' => '0012345678',
    ], JSON_UNESCAPED_UNICODE),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $TOKEN",
        'Content-Type: application/json'
    ]
]);
$result = json_decode(curl_exec($ch), true);
$subId  = $result['submission_id'];

// ── ۳. دانلود PDF ──
$ch2 = curl_init("$BASE/submissions/$subId/pdf");
curl_setopt_array($ch2, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer $TOKEN"]
]);
$pdf = curl_exec($ch2);
file_put_contents("submission_$subId.pdf", $pdf);
echo "✓ ذخیره شد: submission_$subId.pdf";

مستندات APIسامانه تولید فرم PDF

مستندات API
سامانه تولید فرم PDF