API
API
علّم الملفات واكشفها بواجهة API في Markedfile. متاحة فقط على خطتي Business و Enterprise.
مفاتيح API
ينشئ مالك مساحة عمل Business أو Enterprise المفاتيح ويلغيها في إعدادات مساحة العمل. يُعرض المفتاح مرة واحدة. يخزّن Markedfile تجزئة SHA-256 وبادئة قصيرة والاسم. لا يخزّن السر.
ينتمي المفتاح إلى مساحة عمل واحدة بالضبط. يعمل هناك فقط، بحدود خطة تلك المساحة. مساحات العمل الشخصية ليس لها مفاتيح. العضو الذي ليس المالك لا يستطيع إنشاءها أو إلغاءها.
إذا فقدت مساحة العمل خطة Business أو Enterprise النشطة، تتوقف كل المفاتيح عن العمل فوراً، بما في ذلك خلال الأيام الثلاثين التي تبقى فيها الملفات الحالية قابلة للكشف في التطبيق. العودة إلى Business أو Enterprise تعيد عمل المفاتيح التي لم تُلغَ.
المصادقة
أرسل السر في ترويسة Authorization كرمز Bearer. هذه المسارات لا تستخدم ملف تعريف ارتباط للجلسة. يُرفض متصفح على موقع آخر.
التدقيق
الإنشاء والإلغاء والتعليم والكشف تكتب صف تدقيق يستطيع مالك مساحة العمل قراءته. الصف لا يتضمن الملف.
المسارات
POST/api/v1/mark
يعلّم ملفاً ويعيد النسخة المعلَّمة. الجسم بصيغة multipart/form-data.
المصادقة
Authorization: Bearer mf_…أرسل هذه الترويسة. لا يوجد ملف تعريف ارتباط للجلسة. يُقبل curl وعملاء الخادم الآخرون. يُرفض متصفح على موقع آخر.
المعاملات
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| file | file | نعم | الملف المراد تعليمه. تقبل Business و Enterprise حتى 100 MB، و500 صفحة PDF، وفيديو حتى 10 دقائق. يتبع حجم الرفع ومدة الفيديو وعدد صفحات PDF خطة مساحة العمل. |
| identifier | string | نعم | من 1 إلى 32 محرفاً، من دون محارف تحكم. التسمية التي تراها أنت إذا كُشفت هذه النسخة لاحقاً. لا تُكتب في الملف كنص مقروء. |
الطلب
curl -X POST https://markedfile.com/api/v1/mark \
-H "Authorization: Bearer mf_…" \
-F "file=@contract.pdf" \
-F "identifier=northwind"الاستجابة
{
"file": "JVBERi0xLjQK…",
"mime": "application/pdf",
"name": "contract.pdf",
"kind": "pdf",
"layers": [
{
"name": "Metadata",
"detail": "Authenticated workspace reference; the identifier stays on the server",
"screenshot": "No",
"crop": "No",
"reencode": "No"
}
],
"remaining": 1
}file هو البايتات المعلَّمة بصيغة base64. يصف mime و name و kind التنزيل. يسرد layers الحوامل التي طُبّقت. حين لا يكون للخطة حد للملفات النشطة، يكون remaining عدد الملفات النشطة بعد هذا التعليم. حين يكون لها حد، يكون remaining عدد العلامات الجديدة المتبقية. ليس لـ Business و Enterprise حد للملفات النشطة. حذف الملف هو ما ينهي الكشف.
الأخطاء
حقل error في جسم JSON بالإنجليزية.
| الحالة | الوصف |
|---|---|
| 400 | الملف فارغ، أو المعرّف فارغ أو أطول من 32 محرفاً أو يحتوي محرف تحكم. |
| 401 | المفتاح مفقود أو ملغى أو غير معروف. يتضمن جسم JSON الحقل "code": "api-key". |
| 403 | لم تعد مساحة العمل على خطة Business أو Enterprise نشطة (يتضمن الجسم "code": "enterprise")، أو أرسل المتصفح طلباً cross-site أو same-site. |
| 413 | يتجاوز الملف حد الرفع في الخطة، أو يحتوي PDF على صفحات أكثر مما تسمح به الخطة. |
| 422 | تعذّر معالجة الملف. |
| 429 | علّم هذا المفتاح أكثر من 40 ملفاً في الدقيقة الحالية. |
حد المعدل
40 طلباً في الدقيقة لهذا المفتاح. يُخزَّن العداد في قاعدة بيانات المنتج ويبقى بعد إعادة التشغيل.
POST/api/v1/detect
يفحص ملفاً ضمن مساحة عمل هذا المفتاح. الجسم بصيغة multipart/form-data.
المصادقة
Authorization: Bearer mf_…أرسل هذه الترويسة. لا يوجد ملف تعريف ارتباط للجلسة. يُقبل curl وعملاء الخادم الآخرون. يُرفض متصفح على موقع آخر.
المعاملات
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| file | file | نعم | الملف المراد فحصه. يُبحث عن التطابق في مساحة عمل هذا المفتاح فقط. الملف المعلَّم في مساحة عمل أخرى لا يُحل. يمكن لمساحة عمل Business أو Enterprise نشطة أن تفحص ملف فيديو أيضاً. تُفحص لقطة شاشة لإطار واحد كصورة. |
الطلب
curl -X POST https://markedfile.com/api/v1/detect \
-H "Authorization: Bearer mf_…" \
-F "file=@leaked.pdf"الاستجابة
{
"id": "northwind",
"confidence": 0.95,
"layers": [
{
"name": "Metadata",
"hit": true,
"detail": "Authenticated metadata matched this workspace",
"screenshot": "No",
"crop": "No",
"reencode": "No"
}
],
"notes": [
"Confidence is 99% for an exact file or when an authenticated mark agrees with another mark. A visual match alone stays lower, and weak bit agreement stays far from a high score."
]
}id هو المعرّف الذي عيّنته أنت حين عُلّمت تلك النسخة، أو null حين لا يكون لهذه المساحة تطابق. confidence هي 99% لملف مطابق تماماً أو حين تتفق علامة موثّقة مع علامة أخرى. يبقى التطابق البصري وحده أدنى. يسرد layers الحوامل، وتكون hit بقيمة true على التي اتفقت. يصف notes ما فعله الفحص. الملف المحذوف لا يُحل.
الأخطاء
حقل error في جسم JSON بالإنجليزية.
| الحالة | الوصف |
|---|---|
| 400 | الملف فارغ. |
| 401 | المفتاح مفقود أو ملغى أو غير معروف. يتضمن جسم JSON الحقل "code": "api-key". |
| 403 | لم تعد مساحة العمل على خطة Business أو Enterprise نشطة (يتضمن الجسم "code": "enterprise")، أو أرسل المتصفح طلباً cross-site أو same-site. |
| 413 | يتجاوز الملف حد الرفع في الخطة، أو يحتوي PDF على صفحات أكثر مما تسمح به الخطة. |
| 422 | تعذّر معالجة الملف. |
| 429 | أجري هذا المفتاح أكثر من 80 عملية كشف في الدقيقة الحالية. |
حد المعدل
80 طلباً في الدقيقة لهذا المفتاح. يُخزَّن العداد في قاعدة بيانات المنتج ويبقى بعد إعادة التشغيل.