Sign PDF

اختم صورة توقيع PNG مرفوعة واحدة أو أكثر على أي صفحة من ملف PDF. يستخدم هذا المسار عقد multipart مخصّصاً لأنه يحتاج إلى ملف PDF، وصورة توقيع واحدة أو أكثر، وإحداثيات المواضع.

API Endpoint

POST /api/v1/tools/pdf/sign-pdf

يقبل بيانات نموذج multipart. يُرسل ملف PDF بوصفه file؛ وتُرسل التواقيع بوصفها sig0 وsig1 وهكذا؛ وتُرسل المواضع في حقل placements بصيغة JSON.

Parameters

Parameter	Type	Required	Default	Description
file	file	Yes	-	ملف PDF المراد توقيعه
sig0	file	Yes	-	صورة التوقيع الأولى. تستخدم الصور الإضافية sig1 وsig2 وهكذا
placements	JSON string	Yes	-	مصفوفة كائنات المواضع: { "sig": 0, "page": 0, "x": 0.2, "y": 0.7, "w": 0.25, "h": 0.08 }
clientJobId	string	No	-	UUID اختياري لتتبّع التقدّم عبر SSE
fileId	string	No	-	معرّف مكتبة ملفات اختياري لحفظ النتيجة المُوقَّعة كإصدار جديد

Placement Coordinates

Field	Type	Description
sig	integer	فهرس صورة التوقيع. يُطابِق 0 إلى sig0
page	integer	فهرس صفحة PDF يبدأ من الصفر
x	number	الموضع الأيسر ككسر من الصفحة
y	number	الموضع العلوي ككسر من الصفحة
w	number	عرض التوقيع ككسر من الصفحة
h	number	ارتفاع التوقيع ككسر من الصفحة

تستخدم الإحداثيات نقطة أصل في الزاوية العلوية اليسرى. قد تتجاوز القيم حافة الصفحة قليلاً؛ يقصّ عارض PDF الختم النهائي عند حدود الصفحة.

Example Request

curl -X POST http://localhost:1349/api/v1/tools/pdf/sign-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'placements=[{"sig":0,"page":0,"x":0.64,"y":0.82,"w":0.22,"h":0.08}]'

Example Response

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/contract_signed.pdf",
  "previewUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/preview.png",
  "originalSize": 245000,
  "processedSize": 249000
}

إذا تعذّر إنهاء الطلب داخل نافذة الانتظار المتزامنة، يُعيد الـ API:

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

اتصل بـ /api/v1/jobs/<jobId>/progress ونزّل النتيجة عند اكتمال المهمة.

Notes

• صيغة إدخال PDF المقبولة: .pdf.
• يجب أن تكون صور التوقيع ملفات صور صالحة، عادةً بصيغة PNG مع الشفافية.
• يُقبل ما يصل إلى 100 صورة توقيع و100 موضع.
• sign-pdf هو مسار مخصّص ولا يستخدم حقل settings القياسي للأداة بصيغة JSON.