API برای برنامه‌نویس‌ها: کلید، دسترسی و نمونه‌ها

🔑 ساختِ کلید

1. ۱ به «تنظیمات ← API و اتصال‌ها» بروید از منوی کناری «تنظیمات»، زبانه‌ی «API و اتصال‌ها».
2. ۲ «کلید تازه» را بزنید و یک نام بدهید مثلاً «سایت اصلی» یا «CRM»؛ برای هر برنامه یک کلیدِ جدا بسازید.
3. ۳ فقط دسترسی‌های لازم را تیک بزنید برای خواندنِ پاسخ‌ها همان سه دسترسیِ خواندن کافی است.
4. ۴ سقفِ نرخ و انقضا را تعیین کنید پیش‌فرض ۱۲۰ درخواست در دقیقه و بدون انقضا.
5. ۵ کلید را همان لحظه کپی کنید کلیدِ کامل با ff_live_ شروع می‌شود و فقط یک بار نشان داده می‌شود؛ خودِ ما هم نسخه‌ای از آن نداریم.

🧩 دسترسی‌ها (scope)

forms:read — فهرستِ فرم‌ها و آزمون‌ها، ساختار، تنظیمات و لینک‌ها.

forms:write — ساخت، ویرایش، انتشار و حذفِ فرم.

responses:read — فهرست و جزئیاتِ پاسخ‌ها و خروجیِ CSV / Excel.

responses:write — برچسب، یادداشت، ویرایش و حذفِ پاسخ.

reports:read — گزارش‌ها، آمار، داشبوردها و خروجی‌های گزارش.

📡 نشانی، هدر و اولین درخواست

نشانیِ پایه https://porsino.com/api/v1 است و هر درخواست هدرِ Authorization: Bearer با کلیدتان را می‌خواهد. کوکی و توکنِ CSRF لازم نیست.

FORM_ID همان id فرم در خروجیِ فهرستِ فرم‌هاست. هر صفحه‌ی پاسخ‌ها تا ۱۰۰ ردیف دارد؛ با page جلو بروید.

curl -s "https://porsino.com/api/v1/forms?page_size=20" \
  -H "Authorization: Bearer $PORSINO_API_KEY"

curl -s "https://porsino.com/api/v1/forms/FORM_ID/responses?page=1&page_size=50" \
  -H "Authorization: Bearer $PORSINO_API_KEY"

curl -s -o responses.csv "https://porsino.com/api/v1/forms/FORM_ID/responses/export?format=csv" \
  -H "Authorization: Bearer $PORSINO_API_KEY"

🚦 سقفِ نرخ و خطاها

هر کلید سقفِ دقیقه‌ای خودش را دارد (پیش‌فرض ۱۲۰)؛ بیشتر از آن پاسخ 429 با هدرِ Retry-After می‌گیرد.

401 یعنی کلید نامعتبر، باطل‌شده یا منقضی است؛ 403 با کدِ insufficient_scope یعنی دسترسیِ کلید برای آن کار کافی نیست و fields.scope می‌گوید کدام لازم است.

خطاها همیشه یک شکل دارند: error با سه بخشِ code، message و fields. با هدرِ Accept-Language: en پیام انگلیسی می‌شود.

🪝 وب‌هوک: خبرِ لحظه‌ای به‌جای پرس‌وجوی مکرر

برای اینکه با هر پاسخِ تازه به سامانه‌تان خبر برسد، فرم را باز کنید ← زبانه‌ی «اتصال‌ها» و آدرسِ خودتان را بدهید. تلاشِ دوباره خودکار است و لاگِ هر ارسال همان‌جاست.

هر ارسال هدرهای X-FlowForm-Event، X-FlowForm-Delivery، X-FlowForm-Timestamp و X-FlowForm-Signature را دارد. امضا sha256=HMAC-SHA256 روی «timestamp.body» با کلیدِ امضای همان وب‌هوک است؛ ارسالِ قدیمی‌تر از ۵ دقیقه را نپذیرید.

import hmac, hashlib

msg = request.headers["X-FlowForm-Timestamp"].encode() + b"." + raw_body
expected = "sha256=" + hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers["X-FlowForm-Signature"])

🌐 دامنه‌ی اختصاصی

فرم‌ها و آزمون‌ها می‌توانند روی زیردامنه‌ی پرسینو یا دامنه‌ی خودتان باز شوند؛ از «تنظیمات › دامنه‌ی اختصاصی» وصلش کنید (گواهیِ امنیتی خودکار صادر می‌شود).

برای آوردنِ شرکت‌کننده از سایتتان، دکمه یا آیتمِ منو بگذارید (آموزشِ «آزمون روی سایت خودتان و ورود فقط افراد مجاز»).