FormRead वेब API एकीकरण डेवलपर गाइड

FormRead API कैसे काम करता है

FormRead API दो भागों में विभाजित है: फ़ॉर्म प्रबंधित करने (बनाना, अपडेट करना, हटाना और डेटा संग्रहीत करना) के लिए एक REST API, और फ़ॉर्म संपादन और स्कैन किए गए दस्तावेज़ पढ़ने के लिए एक एम्बेडेड iframe। API अकेला फ़ॉर्म प्रोसेस या पढ़ता नहीं है - पढ़ना पूरी तरह से iframe के माध्यम से किया जाता है।

  • REST API (यह पृष्ठ): इसका उपयोग फ़ॉर्म मेटाडेटा बनाने, अपडेट करने, हटाने और पुनर्प्राप्त करने के लिए करें। API आपके फ़ॉर्म डेटा को संग्रहीत करता है और iframe एम्बेड करने के लिए आवश्यक टोकन लौटाता है।
  • Iframe (एम्बेडेड व्यूअर): इसका उपयोग फ़ॉर्म टेम्पलेट संपादित करने, स्कैन किए गए दस्तावेज़ अपलोड करने और परिणाम (OMR, OCR, BCR) निकालने के लिए करें। सभी फ़ॉर्म पढ़ना और डेटा निष्कर्षण iframe के अंदर होता है।
सर्वर-टू-सर्वर प्रोसेसिंग की तलाश है?

यदि आपको विज़ुअल इंटरफ़ेस की आवश्यकता नहीं है और आप केवल इमेज भेजकर JSON के रूप में परिणाम प्राप्त करना चाहते हैं, तो सर्वर-साइड प्रोसेसिंग API देखें।

सामान्य एकीकरण कार्यप्रवाह
  1. Bearer टोकन (डैशबोर्ड से उत्पन्न) के साथ प्रमाणित करें।
  2. फ़ॉर्म बनाने और iframe_token प्राप्त करने के लिए POST /api/forms एंडपॉइंट का उपयोग करें।
  3. उपयोगकर्ताओं को फ़ॉर्म संपादित करने और दस्तावेज़ स्कैन करने देने के लिए iframe_token का उपयोग करके अपने पृष्ठ में iframe एम्बेड करें।
  4. फ़ॉर्म डेटा और निकाले गए परिणाम प्राप्त करने के लिए iframe ईवेंट (editForm, getResults, rowResult) सुनें, फिर उन्हें अपने सिस्टम में संग्रहीत करें।

प्रमाणीकरण

एंटरप्राइज़ उपयोग के लिए, API का उपयोग Bearer Auth टोकन उत्पन्न करके किया जा सकता है।

FormRead डैशबोर्ड में लॉगिन करें और API टोकन विकल्प तक पहुंचें:

FormRead dashboard menu with the API Tokens option highlighted

API टोकन बनाएं ताकि तृतीय-पक्ष सेवाएं आपकी ओर से हमारे एप्लिकेशन से प्रमाणित हो सकें:

Creating a new FormRead API token with permission checkboxes

उत्पन्न टोकन को सुरक्षित स्थान पर कॉपी करें (यह केवल एक बार दिखाया जाएगा):

The generated FormRead API Bearer token shown once - copy and store it securely

नया फ़ॉर्म बनाएं

POST /api/forms

Headers

Name Value
Authorization Bearer YOUR_API_TOKEN
Accept application/json

Request

curl --location --request POST 'https://formread.org/api/forms' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'form_name="new form"' \
  --form 'custom_css="{ingest custom css to edit FormRead View}"'

Response

{
  "id": 8,
  "form_name": "new form",
  "iframe_token": "6ifvCyEcjB3D5SGqtFmJ5eg0sPYNQfLoWCEgv7bb",
  "created_at": "2022-02-28T21:22:55.000000Z",
  "updated_at": "2022-02-28T21:22:55.000000Z"
}

चर custom_css FormRead के स्वरूप को संपादित करने और कस्टम टेक्स्ट जोड़ने के लिए CSS नियमों को शामिल करने की अनुमति देगा, जैसे:

#app-title::after{
  content: 'Your Tittle';
  color: white;
}
#app-subtitle::after{
  content: 'Your Custom sub-tittle Your Custom sub-tittle Your Custom sub-tittle';
  color: white;
}
#upload-from-cam{
  display: none;
}
#upload-from-system{
  background: lightblue;
}
#upload-from-csv{
  display: none;
}
#app > div.bg-gray-50.h-screen.overflow-auto > div > div{
  background-color: black;
}

आईडी द्वारा फ़ॉर्म प्राप्त करें

GET /api/forms/{form_id}

Request

curl --location --request GET 'https://formread.org/api/forms/8' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Response

{
  "id": 8,
  "form_name": "adsf",
  "iframe_token": "po75a0pqut4fa16XWgdEP2qRDwnhgfiqP3H0Dij6",
  "created_at": "2022-02-28T21:22:55.000000Z",
  "updated_at": "2022-03-01T01:40:19.000000Z"
}

फ़ॉर्म संपादित करें

फ़ॉर्म बनाए जाने या GET करने के बाद, इसे प्रतिक्रिया में प्रदान किए गए iframe_token का उपयोग करके Iframe में प्रदर्शित किया जा सकता है (यह टोकन बदलता रहता है, इसलिए iframe प्रस्तुत करने से पहले अपना फ़ॉर्म GET करना सुनिश्चित करें)

नीचे दिए गए उदाहरण की तरह iframe की घटनाओं को सुनने वाली एक स्क्रिप्ट भी बनाएं:

<!DOCTYPE html>
<html style="height: 100%">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body style="height: 100%">

<iframe src="https://formread.org/{lang}/api/forms/{form_id}/edit/{iframe_token}/{read_only}"
        style="height: 100%; width: 100%"></iframe>

<script>
    window.addEventListener('message', function (e) {
        // if (e.origin !== 'https://formread.org') return;

        console.log(e.data.method)

        if (e.data.method === "editForm") {
            let formData = e.data.formData // data used to saved your form
            let schema = JSON.parse(e.data.schema)
            console.log(schema)
            console.log(formData)
        }
        if (e.data.method === "getResults") {
            let results = JSON.parse(e.data.results)
            console.log(results)
        }
        if (e.data.method === "rowResult") {
            let rowResult = JSON.parse(e.data.rowResult)
            console.log(rowResult)
        }
    });
</script>
</body>
</html>

Iframe URL पैरामीटर

पैरामीटर विवरण
lang ऐप कमांड को वांछित भाषा में प्रदर्शित करने के लिए lang चर सेट करें। वर्तमान में, हम अंग्रेजी (en), फ्रेंच (fr), स्पेनिश (es), ब्राज़ीलियाई पुर्तगाली (pt) या कज़ाख (kk) का समर्थन करते हैं
read_only चर read_only को फ़ॉर्म संपादन अक्षम करने के लिए 1 या फ़ॉर्म संपादन की अनुमति देने के लिए 0 पर सेट किया जा सकता है

Iframe ईवेंट

जब उपयोगकर्ता सेव बटन पर क्लिक करते हैं, तो <code class="language-plaintext">editForm</code> विधि ट्रिगर होगी, वहां आपके पास 2 चरों तक पहुंच है:

  • formData चर में एन्कोडेड फ़ॉर्म विशेषताएँ होंगी जिन्हें अपडेट का उपयोग करके आपके फ़ॉर्म में किए गए परिवर्तनों को सहेजने के लिए भेजा जा सकता है:
  • schema चर आपको अब तक बनाए गए फ़ील्ड के बारे में बताएगा:
    {
  "file_name": {
    "type": "text"
  },
  "BCR-0": {
    "type": "text"
  },
  "OCR-1": {
    "type": "text"
  },
  "OMR-2-0": {
    "type": "select",
    "options": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
    "questionIndex": "0"
  },
  "OMR-2-1": {
    "type": "select",
    "options": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
    "questionIndex": "1"
  },
  "OMR-2-2": {
    "type": "select",
    "options": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
    "questionIndex": "2"
  }
}

    चर schema केवल आपके लिए है ताकि आप अपने उपयोगकर्ताओं को कुछ अलर्ट दिखा सकें यदि आप अनिवार्य क्षेत्र फ़ील्ड बनाने की आवश्यकता रखते हैं:

जब कोई उपयोगकर्ता परिणाम डाउनलोड करने पर क्लिक करता है, तो getResults विधि ट्रिगर होगी, वहां आपको परिणाम डेटा JSON प्रारूप में मिलेगा ताकि आप इसे अपने सिस्टम में संग्रहीत कर सकें

इसके अलावा, आप rowResult विधि के साथ पंक्ति दर पंक्ति परिणाम प्राप्त कर सकते हैं, जो हर बार जब कोई पृष्ठ संसाधित होता है तब ट्रिगर होगी

फ़ॉर्म अपडेट करें

PUT /api/forms/{form_id}

Request

curl --location --request POST 'https://formread.org/api/forms/8?_method=PUT' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'form_data="eyJ2dWV4X3N0YXRlIjp7ImZvcm1OYW1lIjoiYWRzZiIsImZvcm1zIjp7f
                     Swic2VsZWN0ZWRGb3JtSWQiOiIiLCJmb3JtUmVhZEFyZWFzIjp7IkJDUi
                     0wIjp7ImNvbHVtblBvc2l0aW9uIjoxLCJ3aWR0aCI6MC4xMTQ5NTA0NTM
                     0MDUzNTE2NCwiaGVpZ2h0IjowL...' \
  --form 'custom_css="{ingest custom css to edit FormRead View}"'

Response

{
  "id": 8,
  "form_name": "adsf",
  "iframe_token": "po75a0pqut4fa16XWgdEP2qRDwnhgfiqP3H0Dij6",
  "created_at": "2022-02-28T21:22:55.000000Z",
  "updated_at": "2022-03-01T02:30:14.000000Z"
}

फ़ॉर्म हटाएं

DELETE /api/forms/{form_id}

Request

curl --location --request DELETE 'https://formread.org/api/forms/8' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Response

1

पूर्ण उदाहरण: ग्रेडिंग वर्कफ़्लो को एम्बेड करना

यहाँ एक एंड-टू-एंड उदाहरण है जो दिखाता है कि कैसे एक शिक्षक एक फॉर्म डिज़ाइन कर सकता है, परीक्षाओं को स्कैन कर सकता है, और ग्रेड किए गए परिणामों को आपके अपने बैकएंड पर पुश कर सकता है - यह सब एक ही पेज से जो FormRead iframe को एम्बेड करता है।

परिदृश्य

एक शिक्षक आपका ऐप खोलता है, "गणित 101 - मिडटर्म" उत्तर पत्रिका डिज़ाइन करता है, इसे प्रिंट करता है, भरी हुई परीक्षाओं को स्कैन करता है, और "परिणाम डाउनलोड करें" पर क्लिक करता है। आपका पेज iframe ईवेंट सुनता है, लेआउट सहेजता है, और ग्रेड किए गए उत्तरों को आपके ग्रेडिंग सिस्टम पर पोस्ट करता है।

चरण 1 - अपने सर्वर से फॉर्म बनाएँ

अपने बैकएंड पर, शिक्षक के लिए एक फॉर्म बनाएँ। आपको एक id और एक iframe_token वापस मिलता है - ये वही हैं जो आप अगले चरण में iframe URL को पास करेंगे।

# From YOUR backend (never from the browser)
curl --location --request POST 'https://formread.org/api/forms' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'form_name="Math 101 - Midterm"'
{
  "id": 42,
  "form_name": "Math 101 - Midterm",
  "iframe_token": "6ifvCyEcjB3D5SGqtFmJ5eg0sPYNQfLoWCEgv7bb",
  "created_at": "2026-04-20T10:00:00.000000Z",
  "updated_at": "2026-04-20T10:00:00.000000Z"
}

अपने डेटाबेस में शिक्षक के रिकॉर्ड के साथ id और iframe_token सहेजें। आप उनका उपयोग चरण 2 में संपादन योग्य iframe प्रस्तुत करने के लिए करेंगे।

चरण 2 - iframe को संपादन योग्य मोड में खोलें

आपका बैकएंड read_only=0 के साथ FormRead iframe वाला एक पेज प्रस्तुत करता है, ताकि शिक्षक शीट पर OMR बुलबुले, OCR क्षेत्र और बारकोड बना सके। जब वे iframe के अंदर "सहेजें" पर क्लिक करते हैं, तो editForm ईवेंट फायर होता है - ब्राउज़र कच्चे formData को आपके अपने बैकएंड पर अग्रेषित करता है। ब्राउज़र कभी भी सीधे FormRead को कॉल नहीं करता है।

<!-- /design-form page rendered by YOUR backend.
     read_only = 0 → editable mode -->
<iframe id="formread-frame"
        src="https://formread.org/en/api/forms/42/edit/6ifvCyEcjB3D5SGqtFmJ5eg0sPYNQfLoWCEgv7bb/0"
        style="width:100%; height:100vh; border:0"></iframe>

<script>
    // The browser ONLY talks to your own backend. Never to FormRead.
    const FORM_ID = 42;

    window.addEventListener('message', async function (e) {
        if (e.origin !== 'https://formread.org') return;

        // Teacher clicked "Save" inside the iframe
        if (e.data.method === 'editForm') {
            await fetch(`/api/forms/${FORM_ID}/layout`, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ form_data: e.data.formData })
            });
        }
    });
</script>

चरण 3 - अपने बैकएंड से लेआउट को स्थायी रूप से सहेजें

आपका बैकएंड formData स्ट्रिंग प्राप्त करता है और इसे PUT के साथ FormRead को अग्रेषित करता है, आपके Bearer टोकन का उपयोग करके (जो कभी सर्वर नहीं छोड़ता)। यह फॉर्म कॉन्फ़िगरेशन को स्थायी रूप से सहेजता है ताकि बाद में उसी फॉर्म का उपयोग परीक्षाओं को स्कैन करने के लिए किया जा सके।

# Inside your backend handler for POST /api/forms/42/layout
# $formData is the raw string your browser posted.
curl --location --request POST 'https://formread.org/api/forms/42?_method=PUT' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form "form_data=${formData}"
{
  "id": 42,
  "form_name": "Math 101 - Midterm",
  "iframe_token": "po75a0pqut4fa16XWgdEP2qRDwnhgfiqP3H0Dij6",
  "created_at": "2026-04-20T10:00:00.000000Z",
  "updated_at": "2026-04-20T10:15:42.000000Z"
}
iframe_token घूमता है

फॉर्म में प्रत्येक अद्यतन एक नया iframe_token लौटाता है। iframe प्रस्तुत करने से ठीक पहले हमेशा अपने बैकएंड से नवीनतम प्राप्त करें - इसे हार्ड-कोड या दीर्घकालिक कैश न करें।

चरण 4 - वर्तमान iframe_token प्राप्त करें

बाद में, जब शिक्षक परीक्षाओं को स्कैन करने के लिए तैयार होता है, तो आपका बैकएंड नवीनतम iframe_token प्राप्त करने के लिए id द्वारा फॉर्म पढ़ता है।

# From YOUR backend, right before rendering the scan page
curl --location --request GET 'https://formread.org/api/forms/42' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
{
  "id": 42,
  "form_name": "Math 101 - Midterm",
  "iframe_token": "po75a0pqut4fa16XWgdEP2qRDwnhgfiqP3H0Dij6",
  "created_at": "2026-04-20T10:00:00.000000Z",
  "updated_at": "2026-04-20T10:15:42.000000Z"
}

चरण 5 - स्कैन करने के लिए iframe को केवल-पढ़ने के मोड में पुनः खोलें

iframe को फिर से प्रस्तुत करें - इस बार URL के अंत में read_only=1 के साथ। शिक्षक अब लेआउट संपादित नहीं कर सकता, केवल स्कैन अपलोड कर सकता है। ब्राउज़र rowResult (प्रति-शीट प्रगति) और getResults (अंतिम डाउनलोड) को आपके बैकएंड पर अग्रेषित करता है।

<!-- /scan-exams page. Note read_only = 1 at the end of the URL. -->
<iframe id="formread-frame"
        src="https://formread.org/en/api/forms/42/edit/po75a0pqut4fa16XWgdEP2qRDwnhgfiqP3H0Dij6/1"
        style="width:100%; height:100vh; border:0"></iframe>

<script>
    const FORM_ID = 42;

    window.addEventListener('message', async function (e) {
        if (e.origin !== 'https://formread.org') return;

        // Live progress while each sheet is processed
        if (e.data.method === 'rowResult') {
            const row = JSON.parse(e.data.rowResult);
            console.log('Processed', row.file_name);
        }

        // Teacher clicked "Download results"
        if (e.data.method === 'getResults') {
            const results = JSON.parse(e.data.results);

            await fetch('/api/grades/bulk', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ form_id: FORM_ID, results })
            });
        }
    });
</script>

चरण 6 - अपने बैकएंड पर परिणामों को संभालें

getResults ईवेंट प्रति संसाधित परीक्षा में एक प्रविष्टि के साथ एक सरणी प्रदान करता है। कुंजियाँ पैटर्न {AreaType}-{AreaIndex}[-{QuestionIndex}] का पालन करती हैं। नीचे वह है जो ब्राउज़र आपके /api/grades/bulk एंडपॉइंट पर पोस्ट करेगा:

[
  {
    "file_name": "student_001.jpg",
    "BCR-0": "20260420-001",
    "OCR-1": "Alice Johnson",
    "OMR-2-0": "3",
    "OMR-2-1": "7",
    "OMR-2-2": "9"
  },
  {
    "file_name": "student_002.jpg",
    "BCR-0": "20260420-002",
    "OCR-1": "Ben Carter",
    "OMR-2-0": "3",
    "OMR-2-1": "6",
    "OMR-2-2": "9"
  }
]
अपना टोकन सर्वर पर रखें

अपने Bearer टोकन को कभी भी ब्राउज़र-सामना करने वाले कोड में उजागर न करें। FormRead API पर सभी create/update/read कॉल आपके अपने बैकएंड के माध्यम से जाती हैं - ब्राउज़र केवल iframe_token देखता है, जो एक ही फॉर्म तक सीमित है।

अक्सर पूछे जाने वाले प्रश्न

FormRead Iframe एकीकरण API क्या है?

यह एक REST API और एक एम्बेड करने योग्य iframe है। आपका बैकएंड REST एंडपॉइंट के माध्यम से फॉर्म प्रबंधित करता है; iframe आपके वेब ऐप के अंदर प्रस्तुत होता है ताकि उपयोगकर्ता आपके इंटरफ़ेस को छोड़े बिना फॉर्म डिज़ाइन कर सकें, स्कैन अपलोड कर सकें और परिणामों की समीक्षा कर सकें।

क्या iframe_token समाप्त या बदलता है?

iframe_token हर बार फॉर्म अपडेट होने पर पुनर्जीवित होता है। iframe प्रस्तुत करने से ठीक पहले हमेशा अपने बैकएंड से FormRead REST API (GET /api/forms/{id}) से नवीनतम मान प्राप्त करें - इसे दीर्घकालिक कैश न करें।

read_only=0 और read_only=1 में क्या अंतर है?

read_only=0 iframe को संपादन योग्य मोड में खोलता है ताकि उपयोगकर्ता फॉर्म डिज़ाइन कर सके (OMR बुलबुले, OCR, बारकोड क्षेत्र रख सके)। read_only=1 इसे केवल स्कैनिंग मोड में खोलता है - उपयोगकर्ता भरी हुई शीट अपलोड कर सकता है और परिणाम डाउनलोड कर सकता है, लेकिन लेआउट नहीं बदल सकता।

क्या मैं अपना API टोकन ब्राउज़र में रख सकता हूँ?

नहीं। Bearer टोकन आपके सर्वर पर रहना चाहिए। FormRead REST API पर सभी create, update और read कॉल आपके अपने बैकएंड के माध्यम से प्रॉक्सी होनी चाहिए। ब्राउज़र को केवल iframe_token की आवश्यकता है, जो एक ही फॉर्म तक सीमित है।

मैं स्कैन किए गए परिणाम कैसे प्राप्त करूँ?

iframe window.postMessage के माध्यम से संदेश पोस्ट करता है। पूर्ण परिणाम सरणी (प्रति स्कैन की गई शीट एक प्रविष्टि) प्राप्त करने के लिए method="getResults" सुनें, और स्कैन करते समय प्रति-शीट प्रगति प्रदर्शित करने के लिए method="rowResult" सुनें।

Postman संग्रह लिंक

Postman संग्रह खोलें

हाथ से फॉर्म ग्रेड करना बंद करें।

FormRead को अभी काम पर लगाएं: अपना फॉर्म बनाएं, अपनी पहली शीट स्कैन करें, और मिनटों में संरचित परिणाम प्राप्त करें।

FormRead का मुफ्त उपयोग शुरू करें डैशबोर्ड पर जाएं

अभी शुरू करें — किसी क्रेडिट कार्ड की आवश्यकता नहीं