ForHosting KIT · المستندات وملفات PDF

التحقق من الحقول المطلوبة وقيم نماذج PDF

قبل تعبئة النموذج، يُطابَق الاسم Ada Lovelace وتاريخ الميلاد 1815-12-10 وخيار البريد الإلكتروني مع أربع قواعد، وتظهر خانة النشرة غير المجاب عنها على أنها اختيارية. ويُرفض تاريخ مثل 2025-02-29. مجاني في متصفحك.

مجاني
يعمل في متصفحك
دون تسجيل
بياناتك لا تغادر جهازك

شغّل الأداة مجانًا اطّلع على الـAPI

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

تحققوا من البيانات المعدة لنموذج PDF قبل بدء تعبئة المستند. قدموا تعريفات الحقول وكائن القيم، فتفحص هذه الإمكانية الحقول المطلوبة والأنواع الدقيقة والتواريخ الحقيقية والخيارات المسموح بها والتعريفات المكررة والمفاتيح غير المتوقعة. وعندما تتطابق البيانات كلها، تعيد مجموعة مرتبة من القيم التي اجتازت التحقق.

حددوا عقد النموذج بوضوح

ابدؤوا بوصف كل حقل في نموذج PDF باسم فريد ونوع مدعوم وعلامة اختيارية تبين إن كان مطلوبا. تشمل الأنواع المتاحة النص والأرقام المحدودة والأعداد الصحيحة والقيم المنطقية وتواريخ ISO والتحديد الفردي والتحديد المتعدد. وتحتاج حقول الاختيار أيضا إلى قائمة خيارات حتى يميز المدقق بين القيمة المعتمدة وأي سلسلة نصية عشوائية.

تمثل التعريفات عقدا لكائن القيم، لذلك يجب أن تقابل كل قيمة مقدمة تعريفا واحدا، وتُرفض أسماء الحقول المكررة لأنها تجعل التحقق ملتبسا. استخدموا أسماء الحقول التي تتوقعها عملية تعبئة PDF اللاحقة كما هي تماما، بما في ذلك حالة الأحرف اللاتينية. لا تفحص هذه الإمكانية ملف PDF ولا تحاول تخمين حقوله.

إن فصل اكتشاف الحقول عن التحقق من القيم يسهل اختبار كل خطوة، ويسمح بإعادة استخدام العقد نفسه مع سجلات كثيرة. تكون قيمة required هي false عند إغفالها، أما الحقل المحدد بوصفه مطلوبا فيجب أن يحتوي على قيمة ذات معنى. وفي الحقول النصية، يُعامل المحتوى المؤلف من مسافات فقط على أنه قيمة مفقودة.

افهموا قواعد التحقق الصارمة من القيم

تُفحص القيم من دون تحويل تلقائي للأنواع. ويجب أن تكون القيمة المنطقية true أو false، لا "yes" ولا 1 ولا 0. تستخدم التواريخ الصيغة الواضحة YYYY-MM-DD ويجب أن تمثل يوما حقيقيا في التقويم، ولذلك تُرفض قيمة مثل 2025-02-29.

يجب أن تطابق قيمة التحديد الفردي إحدى السلاسل المعرفة تماما، مع مراعاة حالة الأحرف. أما التحديد المتعدد فيجب أن يكون array من سلاسل مسموح بها وغير مكررة؛ وتؤدي الخيارات المجهولة أو المتكررة إلى الفشل. تكشف هذه الصرامة أخطاء الربط قبل أن تنتج مستندات تبدو سليمة وهي غير صحيحة.

أما الحالات الفارغة نفسها فتسبب خطأ إذا كان الحقل مطلوبا. تتوقف العملية عند أول مشكلة وتقدم وصفا محددا يستطيع النموذج أو مسار العمل عرضه للمستخدم.

ضعوا التحقق قبل إنشاء ملف PDF

استخدموا هذه الإمكانية مباشرة بعد ربط بيانات التطبيق بأسماء حقول PDF وقبل استدعاء الأداة التي تكتب فعليا داخل المستند. تتضمن النتيجة الناجحة valid true وعدد تعريفات الحقول المفحوصة والقيم المقبولة والحقول الاختيارية التي لم تُقدم. تُرفض المفاتيح المجهولة لأن الخطأ الإملائي في اسم الحقل قد يختفي بصمت أثناء تعبئة PDF.

وهذا يجعل المدقق مفيدا خصوصا في مسارات العمل الدفعية، حيث يمكن أن يؤثر ربط خاطئ واحد في مئات المستندات. احفظوا تعريفات الحقول مع إصدار القالب، وتحققوا من كل سجل وفقا لذلك الإصدار، ثم أرسلوا السجلات الناجحة وحدها إلى مرحلة التعبئة. تعمل الخوارزمية محليا من دون شبكة أو عشوائية أو استدلال نماذج أو حالة مخزنة، لذلك تعطي المدخلات المتطابقة نتائج متطابقة دائما.

حالات الاستخدام

فحص نماذج الانضمام مسبقا

تحققوا من الأسماء والتواريخ والموافقات المنطقية والاختيارات المطلوبة قبل إنشاء نماذج الموظفين أو العملاء المكتملة.

حماية مهام المستندات الدفعية

ارفضوا السجل غير الصالح قبل وصوله إلى طابور كتابة PDF وإنشائه مستندا ناقصا.

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

هل تعدل هذه الإمكانية ملف PDF؟

لا. إنها تتحقق من تعريفات الحقول وقيمها فقط. مرروا القيم المقبولة بعد ذلك إلى إمكانية مستقلة لتعبئة PDF.

كيف يجري التحقق من التواريخ؟

يجب أن تستخدم الصيغة YYYY-MM-DD وتمثل يوما حقيقيا، مع تطبيق قواعد السنوات الكبيسة الصحيحة.

هل يمكن أن تتضمن القيم حقولا غير موجودة في التعريفات؟

لا. تُرفض المفاتيح المجهولة لكشف الأخطاء الإملائية وعمليات الربط القديمة بالقوالب.

ماذا يحدث إذا احتوى حقل مطلوب على مسافات فقط؟

يُعدّ فارغًا، فيفشل التحقق وتذكر الرسالة اسم ذلك الحقل. ولا يكتمل الحقل النصي المطلوب إلا بقيمة لها معنى، أما الحقول الاختيارية الغائبة فتُدرج ببساطة على أنها لم تُرسل.

هل يقبل كلمة «نعم» في خانة اختيار أو عددًا صحيحًا مكتوبًا كنص؟

لا. لا يُحوَّل شيء تلقائيًا: خانة نعم أو لا تحتاج إلى قيمة صحيح أو خطأ، لا إلى كلمة نعم ولا الرقم 1، والعدد الصحيح يجب أن يصل رقمًا لا نصًا مثل 12.

أدوات ذات صلة

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/pdf/fill-form-fields

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/pdf/fill-form-fields \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":[{"name":"full_name","type":"text","required":true},{"name":"age","type":"integer","required":false}],"values":{"full_name":"Ada Lovelace","age":36}}'

const res = await fetch("https://api.kit.forhosting.com/pdf/fill-form-fields", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "fields": [
      {
        "name": "full_name",
        "type": "text",
        "required": true
      },
      {
        "name": "age",
        "type": "integer",
        "required": false
      }
    ],
    "values": {
      "full_name": "Ada Lovelace",
      "age": 36
    }
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/pdf/fill-form-fields",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "fields": [
        {
            "name": "full_name",
            "type": "text",
            "required": true
        },
        {
            "name": "age",
            "type": "integer",
            "required": false
        }
    ],
    "values": {
        "full_name": "Ada Lovelace",
        "age": 36
    }
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/pdf/fill-form-fields", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"fields":[{"name":"full_name","type":"text","required":true},{"name":"age","type":"integer","required":false}],"values":{"full_name":"Ada Lovelace","age":36}}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"fields":[{"name":"full_name","type":"text","required":true},{"name":"age","type":"integer","required":false}],"values":{"full_name":"Ada Lovelace","age":36}}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/pdf/fill-form-fields", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

مثال على الطلب

{
  "fields": [
    {
      "name": "full_name",
      "type": "text",
      "required": true
    },
    {
      "name": "age",
      "type": "integer",
      "required": false
    }
  ],
  "values": {
    "full_name": "Ada Lovelace",
    "age": 36
  }
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "pdf.fill_form_fields",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الحدود

`max_mb`	25
`max_pages`	200

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

ملاحظات تقنية

ولأن العملية حتمية ولا تفتح ملف PDF ولا تعدله، فهي مناسبة للفحص المسبق في المتصفح ولحماية عمليات أتمتة المستندات عبر API بصورة موثوقة.

افهموا قواعد التحقق الصارمة من القيم

يجب أن يصل العدد الصحيح بوصفه رقم JSON بلا جزء كسري، لا بوصفه السلسلة "12". لا تقبل الحقول الرقمية إلا أرقام JSON المحدودة. يمكن أن يكون الحقل الاختياري غائبا أو null أو سلسلة فارغة، وعندئذ يدرج في missing_optional ولا ينسخ إلى validated_values.

ضعوا التحقق قبل إنشاء ملف PDF

يحافظ كائن validated_values على قيم JSON المقبولة كما هي؛ فلا يغير تنسيق التواريخ ولا يقرب الأرقام ولا يعيد ترتيب الاختيارات ولا يخترع قيما افتراضية. يمكن إجراء الفحص التفاعلي في المتصفح، وتبلغ كلفة طلب API واحد $0.002 عند إدخال التحقق ضمن إنتاج المستندات آليا.

حالات التكامل

اختبار ربط القوالب

تأكدوا من استمرار توافق مفاتيح إخراج التطبيق وأنواع JSON مع عقد قالب PDF ذي إصدار محدد.

أسئلة تقنية

ماذا يحدث عند غياب حقل مطلوب؟

يفشل الطلب بخطأ invalid_input يذكر اسم الحقل المطلوب المفقود.

هل تتحول السلاسل الرقمية إلى أرقام؟

لا. التحقق صارم، ولذلك يجب تقديم الرقم أو العدد الصحيح بوصفه رقم JSON.

ما كلفة طلب API؟

يكلف كل طلب $0.002. ويمكن تشغيل المدقق الحتمي في المتصفح أيضا.

اطّلع على توثيق KIT الكامل ←

شغّل الأداة مجانًا

حددوا عقد النموذج بوضوح

افهموا قواعد التحقق الصارمة من القيم

ضعوا التحقق قبل إنشاء ملف PDF

حالات الاستخدام

فحص نماذج الانضمام مسبقا

حماية مهام المستندات الدفعية

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

أدوات ذات صلة

للمطوّرين — الوصول عبر API

الـEndpoint

استدعِ الخدمة من بيئتك

مثال على الطلب

مثال على الاستجابة

الأسعار

الحدود

الأخطاء

ملاحظات تقنية

افهموا قواعد التحقق الصارمة من القيم

ضعوا التحقق قبل إنشاء ملف PDF

حالات التكامل

اختبار ربط القوالب

أسئلة تقنية

شكرًا