واجهة 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%) | 1000 | OCR فقط |
| Growth | $150 | $1350 (−25%) | 4500 | OCR وتحويل 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 يتطلب انتظار التجديد أو تغيير الخطة.
قارن الخطط وإدارة التجديدأول طلب لاستخراج النص
- أنشئ مفتاحًا بصلاحية ocr:process.
- أرسل الملف إلى POST /ocr باستخدام multipart/form-data.
- تحقق من 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_KEY | 401 | أرسل مفتاح API في ترويسة Authorization. |
| INVALID_API_KEY | 401 | المفتاح غير صالح. |
| API_KEY_REVOKED | 401 | أُلغي المفتاح. |
| API_KEY_EXPIRED | 401 | انتهت صلاحية المفتاح. |
| IP_NOT_ALLOWED | 403 | عنوان IP غير مسموح لهذا المفتاح. |
| ACCOUNT_INACTIVE | 403 | الحساب غير نشط. |
| INSUFFICIENT_SCOPE | 403 | المفتاح لا يملك الصلاحية المطلوبة. |
| API_ACCESS_NOT_ENABLED | 403 | المعالجة عبر API غير مفعّلة للحساب. |
| API_DISABLED | 503 | الواجهة غير متاحة مؤقتًا. |
| WORKER_UNAVAILABLE | 503 | خدمة المعالجة مشغولة أو غير متاحة مؤقتًا (503). انتظر حسب Retry-After: 3 ثم أعد المحاولة بعدد محدود؛ لا تُحتسب صفحات للطلب المشغول. |
| STORAGE_UNAVAILABLE | 503 | التخزين غير متاح مؤقتًا. |
| SERVICE_UNAVAILABLE | 503 | الخدمة غير متاحة مؤقتًا. |
| RATE_LIMITED | 429 | طلبات كثيرة؛ انتظر قبل إعادة المحاولة. |
| USAGE_LIMIT_EXCEEDED | 429 | استهلكت رصيد الصفحات المتاح. |
| INVALID_REQUEST | 400 | راجع معلمات الطلب. |
| FILE_TOO_LARGE | 413 | الملف يتجاوز الحجم المسموح. |
| UNSUPPORTED_FILE_TYPE | 415 | صيغة الملف غير مدعومة. |
| INVALID_DOCUMENT | 422 | تعذرت معالجة المستند. |
| OCR_FAILED | 500 | فشل استخراج النص. |
| OCR_TIMEOUT | 504 | انتهت مهلة المعالجة. |
| NOT_FOUND | 404 | المورد غير موجود. |
| JOB_NOT_FOUND | 404 | المهمة غير موجودة. |
| CONFLICT | 409 | الطلب يتعارض مع الحالة الحالية. |
| SERVER_ERROR | 500 | حدث خطأ غير متوقع. |
كيف تُحسب حدود الاستخدام؟
- حد الملف الحالي: 25 MB. حد الصفحات: 30 صفحة لكل مستند، وقد تفرض الخطة أو إعدادات API حدًا أقل.
- الصورة صفحة واحدة، ويُحسب PDF بحسب الصفحات المعالجة.
- تُحتسب صفحات API ضمن رصيد API والرصيد الإجمالي معًا. راجع لوحة الحساب للحدود المتاحة فعليًا.
- يشير 429 RATE_LIMITED إلى كثرة الطلبات، بينما يشير 429 USAGE_LIMIT_EXCEEDED إلى نفاد الرصيد.
التكامل باستخدام مساعد برمجي
زوّد مساعد البرمجة بمواصفة OpenAPI واطلب الالتزام بمساراتها ومعلماتها، مع حفظ المفتاح في متغير بيئة على الخادم. اختبر الطلبات والنتائج؛ لا تفترض أن الكود المولّد صحيح دون مراجعة.
مرجع API النصيمواصفة OpenAPI وأمثلة الطلبات
يمكن استخدام المواصفة لإنشاء عميل برمجي أو استيراد الطلبات في أدوات الاختبار. أمثلة الأوامر أعلاه جاهزة للتعديل بعنوان الملف ومفتاحك.
سجل التحديثات
: تأكيد البريد عند التسجيل، وإنشاء مفاتيح API من الحساب، وحدود استخدام مرتبطة بالخطة.
الإصدار v1: استخراج النص والمهام غير المتزامنة، وقياس الاستهلاك، والإشعارات الموقّعة، ومواصفة OpenAPI.