واجهة برمجة تطبيقات FormRead للمعالجة من جانب الخادم

معالجة النماذج من جانب الخادم

تتيح لك واجهة برمجة تطبيقات FormRead من جانب الخادم إرسال صورة نموذج ممسوحة ضوئيًا واستلام نتائج منظمة (OMR وOCR وBCR) مباشرة بصيغة JSON. بدون متصفح، بدون iframe - مجرد طلب HTTP بسيط من خادمك إلى خادمنا.

• أرسل صورة، واحصل على النتائج بصيغة JSON في طلب واحد.
• يدعم OMR (كشف الفقاعات) وOCR (استخراج النصوص) وBCR (قراءة الباركود وQR).
• يتم تحميل تكوين النموذج تلقائيًا من النموذج الذي قمت بإعداده في لوحة التحكم.

المصادقة

للاستخدامات المؤسسية، يمكن استخدام API عن طريق إنشاء رمز Bearer Auth.

سجل الدخول إلى FormRead لوحة التحكم وادخل إلى خيار رمز API:

أنشئ رموز API للسماح للخدمات الخارجية بالمصادقة مع تطبيقنا نيابة عنك:

معالجة صورة نموذج

أرسل صورة نموذج ممسوحة ضوئيًا لمعالجتها. يجب أن يكون النموذج قد تم إعداده بالفعل بمناطق القراءة (OMR وOCR وBCR) عبر لوحة التحكم أو iframe. تستخدم واجهة برمجة التطبيقات تكوين النموذج المحفوظ لمعالجة الصورة.

العناوين

مع رفع الملف:

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'image=@"/path/to/scanned-form.jpg"'

مع رابط الصورة:

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"image_url": "https://example.com/scanned-form.jpg"}'

استجابة

{
  "success": true,
  "results": {
    "OMR-0-0": "A",
    "OMR-0-1": "C",
    "OMR-0-2": "B,D",
    "OCR-1": "John Smith",
    "BCR-2": "1234567890"
  },
  "omr_details": {
    "OMR-0": {
      "questions": [
        [
          {"left": 0.12, "top": 0.22, "width": 0.02, "height": 0.02, "blackPixelsRatio": 0.72},
          {"left": 0.15, "top": 0.22, "width": 0.02, "height": 0.02, "blackPixelsRatio": 0.15}
        ]
      ]
    }
  },
  "anchor_error": false,
  "processing_time_ms": 450
}

حقول الاستجابة

خيارات إدخال الصورة

يمكنك تقديم الصورة بثلاث طرق. استخدم واحدة بالضبط:

معالجة الدُفعات

لمعالجة صور متعددة لنفس النموذج في طلب واحد، مرر قائمة بعناوين URL مفصولة بفواصل في حقل image_url. تُرجع النتائج كمصفوفة بنفس الترتيب.

الطلب

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"image_url": "https://example.com/a.jpg,https://example.com/b.jpg,https://example.com/c.jpg"}'

استجابة

{
  "results": [
    {
      "id": "0",
      "image_url": "https://example.com/a.jpg",
      "success": true,
      "results": { "OMR-0-0": "A", "OCR-1": "John Smith" },
      "anchor_error": false,
      "processing_time_ms": 430
    },
    {
      "id": "1",
      "image_url": "https://example.com/b.jpg",
      "success": true,
      "results": { "OMR-0-0": "B", "OCR-1": "Jane Doe" }
    },
    {
      "id": "2",
      "image_url": "https://example.com/c.jpg",
      "success": false,
      "error": "Failed to fetch image from URL: 404"
    }
  ],
  "total": 3
}

معلمات الدُفعة

الدفعة مع omr_details

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_url": "https://example.com/a.jpg,https://example.com/b.jpg",
    "details": true
  }'

الحدود

تبدو استجابة 429 على النحو التالي:

{
  "message": "Too Many Attempts."
}

يُحتسب الطلب الدفعي كطلب واحد بغض النظر عن عدد عناوين URL التي يحتويها.

أنواع المناطق المدعومة

أمثلة على الكود

إليك أمثلة كاملة بلغة Python و JavaScript لمعالجة صورة نموذج:

Python

import requests

API_URL = "https://formread.org/api/forms/{form_id}/process"
TOKEN = "YOUR_API_TOKEN"

with open("scanned-form.jpg", "rb") as f:
    response = requests.post(
        API_URL.format(form_id=123),
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {TOKEN}",
        },
        files={"image": f},
    )

data = response.json()
print(data["results"])
# {"OMR-0-0": "A", "OMR-0-1": "C", "OCR-1": "John Smith"}

Node.js

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('image', fs.createReadStream('scanned-form.jpg'));

const response = await axios.post(
  'https://formread.org/api/forms/123/process',
  form,
  {
    headers: {
      ...form.getHeaders(),
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_API_TOKEN',
    },
  }
);

console.log(response.data.results);
// { 'OMR-0-0': 'A', 'OMR-0-1': 'C', 'OCR-1': 'John Smith' }

الأسئلة الشائعة