FormRead Web API Entegrasyon Geliştirici Kılavuzu

FormRead API Nasıl Çalışır

FormRead API iki bölüme ayrılmıştır: formları yönetmek (oluşturma, güncelleme, silme ve veri depolama) için bir REST API ve form düzenleme ile taranmış belgeleri okuma için gömülebilir bir iframe. API tek başına formları işlemez veya okumaz - okuma işlemi tamamen iframe aracılığıyla gerçekleştirilir.

• REST API (bu sayfa): Form meta verilerini oluşturmak, güncellemek, silmek ve almak için kullanın. API, form verilerinizi depolar ve iframe'i gömmek için gereken token'ları döndürür.
• Iframe (gömülü görüntüleyici): Form şablonlarını düzenlemek, taranmış belgeleri yüklemek ve sonuçları (OMR, OCR, BCR) çıkarmak için kullanın. Tüm form okuma ve veri çıkarma işlemleri iframe içinde gerçekleşir.

Kimlik Doğrulama

Kurumsal kullanımlar için API, bir Bearer Auth jetonu oluşturularak kullanılabilir.

FormRead pano paneline giriş yapın ve API Token seçeneğine erişin:

Üçüncü taraf hizmetlerin sizin adınıza uygulamamızla kimlik doğrulaması yapabilmesi için API jetonlarını oluşturun:

Oluşturulan jetonu güvenli bir yere kopyalayın (yalnızca bir kez gösterilecektir):

Yeni Form Oluştur

Üstbilgiler

İstek

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}"'

Yanıt

{
  "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 değişkeni, FormRead görünümünü düzenlemek ve özel metin eklemek için css kurallarını almanıza olanak tanır, örneğin:

#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;
}

Id ile Form Getir

İstek

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

Yanıt

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

Bir Formu Düzenle

Bir form Oluşturulduktan veya GET ile alındıktan sonra, yanıtta verilen iframe_token kullanılarak bir Iframe içinde görüntülenebilir (bu jeton değişir, bu nedenle iframe'i oluşturmadan önce formunuzu GET ile aldığınızdan emin olun)

Aşağıdaki örnekte olduğu gibi iframe'in olaylarını dinleyen bir komut dosyası da oluşturun:

<!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 Parametreleri

Iframe Olayları

Kullanıcılar kaydet düğmesine tıkladığında, <code class="language-plaintext">editForm</code> metodu tetiklenecek ve burada 2 değişkene erişebileceksiniz:

• formData değişkeni, formunuzda yapılan değişiklikleri kaydetmek için Güncelleme kullanılarak gönderilebilecek kodlanmış form özniteliklerini içerecektir:
• schema değişkeni, şimdiye kadar oluşturulan alanları bilmenizi sağlayacaktır:

  {
    "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 değişkeni, yalnızca zorunlu alanların oluşturulmasını gerektirdiğiniz durumlarda kullanıcılarınıza bazı uyarılar göstermeniz içindir:

Bir kullanıcı sonuçları indirmeye tıkladığında, getResults metodu tetiklenecek ve sonuç verilerini JSON formatında alacaksınız, böylece bunları sisteminizde saklayabilirsiniz

Ayrıca, her sayfa işlendiğinde tetiklenecek olan rowResult metodu ile satır satır sonuçları alabilirsiniz

Formu Güncelle

İstek

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}"'

Yanıt

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

Formu Sil

İstek

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

Yanıt

1

Tam Örnek: Notlandırma İş Akışını Yerleştirme

Bir öğretmenin bir form tasarlayıp sınavları tarayarak notlandırılmış sonuçları kendi arka ucuna göndermesini gösteren uçtan uca bir örnek - tamamı FormRead iframe'ini barındıran tek bir sayfadan.

Adım 1 - Formu sunucunuzdan oluşturun

Arka ucunuzda, öğretmen için bir form oluşturun. Bir id ve iframe_token alırsınız - bunları bir sonraki adımda iframe URL'sine ileteceksiniz.

# 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 ve iframe_token'ı kendi veritabanınızdaki öğretmenin kaydına kaydedin. Bunları adım 2'de düzenlenebilir iframe'i görüntülemek için kullanacaksınız.

Adım 2 - iframe'i düzenlenebilir modda açın

Arka ucunuz, read_only=0 ile FormRead iframe'ini içeren bir sayfa görüntüler, böylece öğretmen kağıda OMR baloncukları, OCR alanları ve barkodlar çizebilir. İframe içinde "Kaydet"e tıkladıklarında, editForm olayı tetiklenir - tarayıcı ham formData'yı kendi arka ucunuza iletir. Tarayıcı doğrudan FormRead'i çağırmaz.

<!-- /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>

Adım 3 - Düzeni arka ucunuzdan kalıcı olarak kaydedin

Arka ucunuz formData dizesini alır ve sunucudan hiç ayrılmayan Bearer token'ınızı kullanarak bir PUT isteği ile FormRead'e iletir. Bu, aynı formun daha sonra sınavları taramak için yeniden kullanılabilmesi için form yapılandırmasını kalıcı olarak kaydeden işlemdir.

# 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"
}

Adım 4 - Geçerli iframe_token'ı alın

Daha sonra, öğretmen sınavları taramaya hazır olduğunda, arka ucunuz en son iframe_token'ı almak için formu id ile okur.

# 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"
}

Adım 5 - Taramak için iframe'i salt okunur modda yeniden açın

İframe'i yeniden, bu sefer URL'nin sonunda read_only=1 ile görüntüleyin. Öğretmen artık düzeni düzenleyemez, yalnızca taramaları yükleyebilir. Tarayıcı rowResult (sayfa başına ilerleme) ve getResults (son indirme) verilerini arka ucunuza iletir.

<!-- /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>

Adım 6 - Sonuçları arka ucunuzda işleyin

getResults olayı, işlenen her sınav için bir giriş içeren bir dizi döndürür. Anahtarlar {AlanTürü}-{Alanİndeksi}[-{Soruİndeksi}] modelini izler. Aşağıda, tarayıcının /api/grades/bulk uç noktanıza göndereceği örnek verilmiştir:

[
  {
    "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"
  }
]

Sıkça Sorulan Sorular

Postman Koleksiyon Bağlantısı