محدود دائرہ والے مینجمنٹ API ٹوکن سے جمع آوریاں پڑھیں

مینجمنٹ API FormFlow کا پڑھنے والا پہلو ہے: پانچ GET راستے، ایک بیئرر ٹوکن، اور کچھ بھی لکھنے کا کوئی طریقہ نہیں۔ یہ وہی سطح ہے جو ٹیم کے اپنے اوزار تب استعمال کرتے ہیں جب انہیں FormFlow کے پاس پہلے سے محفوظ جمع آوریاں چاہیے ہوں، کسی اسپریڈ شیٹ میں رکھی نقل نہیں۔

ٹوکن کو کام جتنا ہی تنگ رکھیں

ٹوکن ٹیم کا ہوتا ہے، کسی شخص کا نہیں۔ بناتے وقت اسے نام، کم از کم ایک قابلیت — submissions:read، refusals:read یا forms:read —، اختیاری طور پر فارمز کی فہرست، اور اختیاری طور پر میعاد کی تاریخ دی جاتی ہے۔ FormFlow صرف ہیش رکھتا ہے، اس لیے اسناد بناتے وقت ایک بار دکھائی جاتی ہیں، اس کے بعد کبھی نہیں۔ منسوخی فوراً لاگو ہوتی ہے؛ میعاد ختم شدہ ٹوکن اپنی سطر رکھتا ہے اور اپنی جگہ خالی کر دیتا ہے۔

ان میں سے دو ترتیبات سب سے زیادہ کام کرتی ہیں۔ نامزد فارمز تک محدود ٹوکن انہی فارمز تک پہنچتا ہے اور کہیں نہیں۔ صرف forms:read والا ٹوکن فارمز کی میٹاڈیٹا فہرست دیکھ سکتا ہے، ایک بھی جمع آوری پڑھے بغیر۔ ان میں سے کوئی ترجیح نہیں: ٹوکن کے دائرے سے باہر کی پڑھائی بالکل ویسا ہی جواب دیتی ہے جیسا کسی نہ موجود ریکارڈ کی پڑھائی، اس لیے غائب اور ممنوع ریکارڈ ایک جیسے لگتے ہیں۔

پانچ پڑھائیاں

ہر راستہ /api/v1/manage کے نیچے ہے اور Authorization ہیڈر میں بیئرر ٹوکن سے تصدیق ہوتا ہے۔

• GET /api/v1/manage/forms — فارمز کی میٹاڈیٹا۔ forms:read درکار۔

• GET /api/v1/manage/submissions — جمع آوریوں کا ایک صفحہ۔ submissions:read درکار۔

• GET /api/v1/manage/submissions/{uuid} — ایک جمع آوری، ان اسپام اشاروں سمیت جو فہرست چھوڑ دیتی ہے۔

• GET /api/v1/manage/refused-submissions — وہ مستردات جو فارم کے رجسٹر نے رکھے۔ refusals:read درکار۔

• GET /api/v1/manage/attempts/{attemptId} — ایک کوشش کی ترتیب وار زندگی، تمام رجسٹروں میں جنہوں نے اسے درج کیا۔

جمع آوری کی باڈی فیلڈ ناموں سے کلید والی ہوتی ہے اور جیسی بھیجی گئی تھی ویسی ہی واپس آتی ہے۔ زیادہ تر فیلڈز متن ہیں، ملٹی سلیکٹ فہرست ہے، فائل فیلڈ اپنے محفوظ نام کے ساتھ حوالہ ہے، اور گرڈ قطار کے لیبل سے کلید والی شے ہے۔ صرف ایک جمع آوری والا راستہ اسپام اشارے واپس کرتا ہے۔

کرسر سے صفحہ بندی کریں

فہرست کے راستے data اور meta واپس کرتے ہیں۔ limit 1 سے 200 لیتا ہے اور طے شدہ 50 ہے، اور ترتیب created_at پھر id، نزولی ہے۔ meta.has_more بتاتا ہے کہ اگلا صفحہ ہے یا نہیں؛ meta.next_cursor وہ غیر واضح قدر ہے جو cursor کے طور پر واپس بھیجی جاتی ہے۔ یہاں آفسیٹ نہیں ہے، کیونکہ پڑھتے وقت مجموعہ ہلتا رہتا ہے اور آفسیٹ خاموشی سے قطاریں چھوڑ یا دہرا دے گا۔

cursor=""
while :; do
  page=$(curl -sS "https://formflow.digital/api/v1/manage/submissions?limit=100&cursor=$cursor" \
    -H "Authorization: Bearer $FORMFLOW_TOKEN")
  echo "$page" | jq -r '.data[] | [.uuid, .form_id, .created_at] | @tsv'
  cursor=$(echo "$page" | jq -r '.meta.next_cursor // empty')
  [ "$(echo "$page" | jq -r '.meta.has_more')" = "true" ] || break
done

فلٹر جان بوجھ کر تنگ ہیں: form_id، since، until، is_spam، unread اور q۔ q بلائنڈ انڈیکس پر درست ٹوکن تلاش ہے، ذیلی متن کی تلاش نہیں، اور صرف وہیں جواب دیتی ہے جہاں تلاش کی فہرست بندی فعال ہو۔

ایک مستردہ سے اس کی کوشش تک

مستردہ جمع آوری اور جمع آوری الگ ریکارڈ ہیں۔ مستردہ اس لیے رکھا جاتا ہے کہ گاہک اس پر کارروائی کر سکے؛ وہ کبھی پہنچایا نہیں جاتا اور کبھی شمار شدہ جمع آوری نہیں بنتا۔ دونوں میں کوشش کی شناخت ہوتی ہے، اور کوشش کا راستہ اسی کوشش کا سلسلہ جوڑتا ہے — پری فلائٹ رگڑ، مستردہ، قبولیت، بچاؤ، بازیابی، رسید اور ہر ترسیل کی ذمہ داری — بغیر کسی بھیجی گئی قدر یا جمع کرانے والے کی میٹاڈیٹا کے۔

کوشش کی شناخت بذات خود منفرد نہیں ہوتی، اس لیے سلسلہ ہمیشہ ایک فارم تک محدود رہتا ہے۔ جب وہ شناخت ایک سے زیادہ فارمز پر ہو، جواب 409 ہوتا ہے اور ان کے نام بتاتا ہے، اور آپ form_uuid کے ساتھ درخواست دہراتے ہیں تاکہ چن سکیں۔

جہاں پڑھنے کی سطح کند ہے

اس پر کچھ بنانے سے پہلے تین اور حدیں جان لیں۔ باڈیز FormFlow کے اندر ڈکرپٹ ہوتی ہیں اور جیسی محفوظ تھیں ویسی واپس آتی ہیں، اس لیے جمع آوریاں پڑھنے والا ٹوکن ذاتی ڈیٹا پڑھنے والا ٹوکن ہے، اور اس کا ذخیرہ اسناد جیسی احتیاط مانگتا ہے۔ جس سطر کی باڈی ڈکرپٹ نہ ہو سکے وہ payload_error کے ساتھ payload_unavailable واپس کرتی ہے جبکہ صفحے کا باقی حصہ آتا رہتا ہے۔ اور کوڈ درست ہیں: ناجائز، میعاد ختم یا منسوخ ٹوکن پر 401؛ قابلیت نہ ہونے یا پلان دستیاب نہ ہونے پر 403؛ ریکارڈ ٹوکن کے دائرے سے باہر ہونے پر 404؛ ناجائز فلٹر یا کرسر پر 422؛ اور شرح کی حد پر 429، Retry-After کے ساتھ۔

پورا معاہدہ — ہر پیرامیٹر، جواب کی ساخت اور خرابی — /docs/api میں ہے۔ اور v1.0.0 کی تبدیلیوں کے ریکارڈ کا اندراج اس API کو جیسا آیا ویسا درج کرتا ہے: جمع آوریاں وصول کرنے والے اسی واحد اینڈ پوائنٹ کے ساتھ ایک دستاویزی مینجمنٹ API۔