تخطٍّ إلى المحتوى

واجهة Zegi لاستخراج النص العربي والإنجليزي

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

https://zegi.ae/api/v1

كيف أنشئ مفتاح API؟

أنشئ حسابًا وأكّد بريدك الإلكتروني، ثم افتح لوحة مفاتيح API وحدّد الصلاحيات اللازمة. يظهر المفتاح الكامل مرة واحدة؛ احفظه في إعدادات الخادم ولا تضعه في كود المتصفح أو عنوان URL.

يتطلب API اشتراكاً ببطاقة. تشمل التجربة 7 أيام و800 صفحة إجمالاً. تتشارك مفاتيح الحساب الرصيد نفسه. يعرض الطلب GET /account الخطة والرصيد الفعلي.

Authorization: Bearer <API_KEY>

الاشتراكات وميزات API

أدوات الموقع مجانية دون تسجيل. يتطلب إنشاء مفتاح API حساباً مؤكداً واشتراكاً ببطاقة. تشمل التجربة 7 أيام و800 صفحة إجمالاً، مع ميزات الخطة المختارة. يبدأ التحصيل تلقائياً بعد التجربة ما لم تُلغِ التجديد.

الخطةشهرياً بالدولارالدفع السنوي بالدولارالصفحات شهرياًالميزات
Starter$50$480 (−20%)1000OCR فقط
Growth$150$1350 (−25%)4500OCR وتحويل PDF إلى Word وExcel
Unlimited$300$2700 (−25%)غير محدودةكل واجهات الأدوات: OCR والتحويل والضغط والتحسين والدمج والتقسيم وPDF القابل للبحث

الدفع السنوي مقدماً؛ رصيد الصفحات يتجدد شهرياً ولا يتحول إلى رصيد سنوي. تتشارك جميع المفاتيح رصيد الحساب. Unlimited يلغي حد الصفحات الشهري فقط؛ حدود الملف والطلب ومعدل الطلبات تبقى سارية. لا تمنح صلاحية المفتاح ميزة غير مشمولة بالخطة.

راجع GET /account للحدود الفعلية. API_ACCESS_NOT_ENABLED يعني أن الاشتراك غير موجود أو غير نشط؛ INSUFFICIENT_SCOPE يعني أن صلاحية المفتاح ناقصة أو أن الخطة لا تشمل الميزة. لا تُعد إرسال الطلب دون إصلاح السبب. استخدم Retry-After عند RATE_LIMITED؛ نفاد الرصيد USAGE_LIMIT_EXCEEDED يتطلب انتظار التجديد أو تغيير الخطة.

قارن الخطط وإدارة التجديد

أول طلب لاستخراج النص

  1. أنشئ مفتاحًا بصلاحية ocr:process.
  2. أرسل الملف إلى POST /ocr باستخدام multipart/form-data.
  3. تحقق من data.files[0].ok ثم اقرأ data.files[0].text. قد يفشل ملف منفرد حتى عند نجاح طلب الدفعة.
curl -X POST "https://zegi.ae/api/v1/ocr" \
  -H "Authorization: Bearer $ZEGI_API_KEY" \
  -F "file=@document.png"

ما الملفات والنتائج المدعومة؟

تقبل الواجهة الصور وملفات PDF الرقمية والممسوحة. أرسل الحقل file أو files، وأضف ?includeLayout=true لإرجاع إحداثيات الكلمات في الصفحات. راجع مواصفة OpenAPI للصيغ والمعلمات كاملة.

قد يتضمن الحقل structured بيانات فاتورة أو إيصال أو جواز سفر عند التعرّف عليها. الحقول غير المؤكدة قد تكون فارغة؛ استخراج النص لا يثبت صحة المستند أو هوية صاحبه.

كيف أتابع مهمة غير متزامنة؟

أرسل ?async=true لتحصل على استجابة 202 ومعرّف job_id، ثم تابع الحالة عبر GET /ocr/jobs/{id}. استخدم ترويسة Idempotency-Key عند إعادة إرسال الطلب نفسه لتجنّب إنشاء مهمة مكررة.

# 1) Submit — returns 202 with a job_id
curl -X POST "https://zegi.ae/api/v1/ocr?async=true" \
  -H "Authorization: Bearer $ZEGI_API_KEY" \
  -H "Idempotency-Key: my-unique-key-001" \
  -F "file=@large.pdf"

# 2) Poll until status is "completed"
curl "https://zegi.ae/api/v1/ocr/jobs/JOB_ID" \
  -H "Authorization: Bearer $ZEGI_API_KEY"

إشعارات Webhook والتحقق من توقيعها

سجّل عنوان الاستقبال باستخدام POST /webhooks. تحقق من X-Zegi-Signature بحساب HMAC-SHA256 على `${timestamp}.${body}` باستخدام جسم الطلب الأصلي، وارفض الطوابع الزمنية الأقدم من خمس دقائق. تُرسل أيضًا ترويسة X-AjmanOCR-Signature للتوافق مع التكاملات السابقة.

الأحداث: ocr.completedocr.failedtool.completedtool.failed

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, headers, secret) {
  const ts = headers["x-zegi-timestamp"] ?? headers["x-ajmanocr-timestamp"]; // legacy fallback
  const sig = headers["x-zegi-signature"] ?? headers["x-ajmanocr-signature"]; // "v1=<hex>"
  const expected = "v1=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window
  return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

صلاحيات مفاتيح API

الصلاحيةالاستخدام
ocr:readقراءة مهام استخراج النص ونتائجها.
ocr:processإرسال المستندات لاستخراج النص.
documents:readقراءة المستندات المحفوظة ونتائجها.
documents:writeإنشاء المستندات المحفوظة وتعديلها وحذفها.
compression:readقراءة مهام الضغط ونتائجها.
compression:processإرسال الملفات للضغط أو التحويل.
exports:readتصدير النتائج بالصيغ المدعومة.
usage:readقراءة الاستهلاك والحدود وحالة المفاتيح.
webhooks:readقراءة نقاط استقبال الإشعارات وحالة التسليم.
webhooks:writeإدارة نقاط استقبال الإشعارات.
pdf:mergeدمج ملفات PDF.
pdf:splitتقسيم PDF إلى صفحات أو نطاقات.
pdf:convertتحويل PDF إلى Word أو Excel.
pdf:searchableإنشاء PDF قابل للبحث.
image:enhanceتحسين الصور وتكبيرها.

رموز الأخطاء

اعتمد في معالجة الأخطاء على error.code وحالة HTTP، وليس نص الرسالة الذي قد يتغير.

الرمزHTTPالمعنى
MISSING_API_KEY401أرسل مفتاح API في ترويسة Authorization.
INVALID_API_KEY401المفتاح غير صالح.
API_KEY_REVOKED401أُلغي المفتاح.
API_KEY_EXPIRED401انتهت صلاحية المفتاح.
IP_NOT_ALLOWED403عنوان IP غير مسموح لهذا المفتاح.
ACCOUNT_INACTIVE403الحساب غير نشط.
INSUFFICIENT_SCOPE403المفتاح لا يملك الصلاحية المطلوبة.
API_ACCESS_NOT_ENABLED403المعالجة عبر API غير مفعّلة للحساب.
API_DISABLED503الواجهة غير متاحة مؤقتًا.
WORKER_UNAVAILABLE503خدمة المعالجة مشغولة أو غير متاحة مؤقتًا (503). انتظر حسب Retry-After: 3 ثم أعد المحاولة بعدد محدود؛ لا تُحتسب صفحات للطلب المشغول.
STORAGE_UNAVAILABLE503التخزين غير متاح مؤقتًا.
SERVICE_UNAVAILABLE503الخدمة غير متاحة مؤقتًا.
RATE_LIMITED429طلبات كثيرة؛ انتظر قبل إعادة المحاولة.
USAGE_LIMIT_EXCEEDED429استهلكت رصيد الصفحات المتاح.
INVALID_REQUEST400راجع معلمات الطلب.
FILE_TOO_LARGE413الملف يتجاوز الحجم المسموح.
UNSUPPORTED_FILE_TYPE415صيغة الملف غير مدعومة.
INVALID_DOCUMENT422تعذرت معالجة المستند.
OCR_FAILED500فشل استخراج النص.
OCR_TIMEOUT504انتهت مهلة المعالجة.
NOT_FOUND404المورد غير موجود.
JOB_NOT_FOUND404المهمة غير موجودة.
CONFLICT409الطلب يتعارض مع الحالة الحالية.
SERVER_ERROR500حدث خطأ غير متوقع.

كيف تُحسب حدود الاستخدام؟

  • حد الملف الحالي: 25 MB. حد الصفحات: 30 صفحة لكل مستند، وقد تفرض الخطة أو إعدادات API حدًا أقل.
  • الصورة صفحة واحدة، ويُحسب PDF بحسب الصفحات المعالجة.
  • تُحتسب صفحات API ضمن رصيد API والرصيد الإجمالي معًا. راجع لوحة الحساب للحدود المتاحة فعليًا.
  • يشير 429 RATE_LIMITED إلى كثرة الطلبات، بينما يشير 429 USAGE_LIMIT_EXCEEDED إلى نفاد الرصيد.
مقارنة الخطط

التكامل باستخدام مساعد برمجي

زوّد مساعد البرمجة بمواصفة OpenAPI واطلب الالتزام بمساراتها ومعلماتها، مع حفظ المفتاح في متغير بيئة على الخادم. اختبر الطلبات والنتائج؛ لا تفترض أن الكود المولّد صحيح دون مراجعة.

مرجع API النصي

مواصفة OpenAPI وأمثلة الطلبات

يمكن استخدام المواصفة لإنشاء عميل برمجي أو استيراد الطلبات في أدوات الاختبار. أمثلة الأوامر أعلاه جاهزة للتعديل بعنوان الملف ومفتاحك.

سجل التحديثات

: تأكيد البريد عند التسجيل، وإنشاء مفاتيح API من الحساب، وحدود استخدام مرتبطة بالخطة.

الإصدار v1: استخراج النص والمهام غير المتزامنة، وقياس الاستهلاك، والإشعارات الموقّعة، ومواصفة OpenAPI.