स्कोप वाले मैनेजमेंट 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।