mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
---
|
|
description: "ختم صور توقيع مرفوعة على ملف PDF باستخدام مواضع صفحات مُطبَّعة."
|
|
i18n_source_hash: c28f78c2e7fd
|
|
i18n_provenance: human
|
|
i18n_output_hash: c0419e50518e
|
|
---
|
|
|
|
# Sign PDF {#sign-pdf}
|
|
|
|
اختم صورة توقيع PNG مرفوعة واحدة أو أكثر على أي صفحة من ملف PDF. يستخدم هذا المسار عقد multipart مخصّصاً لأنه يحتاج إلى ملف PDF، وصورة توقيع واحدة أو أكثر، وإحداثيات المواضع.
|
|
|
|
## API Endpoint {#api-endpoint}
|
|
|
|
`POST /api/v1/tools/pdf/sign-pdf`
|
|
|
|
يقبل بيانات نموذج multipart. يُرسل ملف PDF بوصفه `file`؛ وتُرسل التواقيع بوصفها `sig0` و`sig1` وهكذا؛ وتُرسل المواضع في حقل `placements` بصيغة JSON.
|
|
|
|
## Parameters {#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 {#placement-coordinates}
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| sig | integer | فهرس صورة التوقيع. يُطابِق `0` إلى `sig0` |
|
|
| page | integer | فهرس صفحة PDF يبدأ من الصفر |
|
|
| x | number | الموضع الأيسر ككسر من الصفحة |
|
|
| y | number | الموضع العلوي ككسر من الصفحة |
|
|
| w | number | عرض التوقيع ككسر من الصفحة |
|
|
| h | number | ارتفاع التوقيع ككسر من الصفحة |
|
|
|
|
تستخدم الإحداثيات نقطة أصل في الزاوية العلوية اليسرى. قد تتجاوز القيم حافة الصفحة قليلاً؛ يقصّ عارض PDF الختم النهائي عند حدود الصفحة.
|
|
|
|
## Example Request {#example-request}
|
|
|
|
```bash
|
|
curl -X POST http://localhost:1349/api/v1/tools/pdf/sign-pdf \
|
|
-H "Authorization: Bearer si_your-api-key" \
|
|
-F "file=@contract.pdf" \
|
|
-F "sig0=@signature.png" \
|
|
-F 'placements=[{"sig":0,"page":0,"x":0.64,"y":0.82,"w":0.22,"h":0.08}]'
|
|
```
|
|
|
|
## Example Response {#example-response}
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"async": true
|
|
}
|
|
```
|
|
|
|
اتصل بـ `/api/v1/jobs/<jobId>/progress` ونزّل النتيجة عند اكتمال المهمة.
|
|
|
|
## Notes {#notes}
|
|
|
|
- صيغة إدخال PDF المقبولة: `.pdf`.
|
|
- يجب أن تكون صور التوقيع ملفات صور صالحة، عادةً بصيغة PNG مع الشفافية.
|
|
- يُقبل ما يصل إلى 100 صورة توقيع و100 موضع.
|
|
- `sign-pdf` هو مسار مخصّص ولا يستخدم حقل `settings` القياسي للأداة بصيغة JSON.
|