# Embroidery File Converter Developer API

الصفحة القانونية: https://embroideryfileconverter.com/ar/developers

أنشئ سير عمل تطريز باستخدام واجهة REST خاصة للرقمنة من الصور وتحويل الملفات وحالة الوظائف والمخرجات المعتمدة والتنزيلات الموقعة.

## اختر التكامل المناسب

- استخدم REST API في هذه الصفحة لخادم خلفي أو منتج SaaS أو سير عمل تجارة إلكترونية أو أتمتة أو تطبيق من جانب الخادم.
- استخدم [وثائق وكيل الذكاء الاصطناعي وMCP](https://embroideryfileconverter.com/ar/ai-agents) عندما يجب أن يتصرف مساعد نيابة عن مستخدم عبر OAuth.

لا تضع مفتاح API للمطور في JavaScript المتصفح أو تطبيق جوال أو ثنائي سطح مكتب موزع.

## عنوان URL الأساسي والمصادقة

- عنوان URL الأساسي: `https://embroideryfileconverter.com/api/developer/v1`
- المصادقة: `Authorization: Bearer efc_live_...`
- نوع محتوى المهمة: `multipart/form-data`
- الحد العام الافتراضي للمعدل: 60 طلبات في الدقيقة لكل مفتاح، مع سقف شبكة منفصل
- عمر عنوان URL للملف الموقَّع: 10 دقيقة
- [وصف OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [إنشاء أو إبطال مفاتيح API](https://embroideryfileconverter.com/developers/keys)

تُعرض مفاتيح API مرة واحدة، وتُخزن فقط كتجزئات SHA-256، وتنتهي صلاحيتها، ويمكن إبطالها فوراً. القدرات المتاحة هي `formats:read` و`usage:read` و`jobs:read` و`jobs:write`.

## البداية السريعة: إنشاء مهمة تحويل

```bash
curl -X POST https://embroideryfileconverter.com/api/developer/v1/jobs \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json" \
  -F "workflow=conversion" \
  -F "format=dst" \
  -F "file=@design.pes"
```

ترجع واجهة API HTTP 202 لأن المعالجة غير متزامنة:

```json
{
  "message": "Processing started.",
  "job": {
    "id": "01JEXAMPLEJOBID000000000",
    "status": "queued",
    "workflow": "conversion"
  },
  "jobs": [
    {
      "id": "01JEXAMPLEJOBID000000000",
      "status": "queued",
      "workflow": "conversion"
    }
  ],
  "freeUsage": {
    "previewRemaining": 2,
    "creditBalance": 0
  }
}
```

احتفظ بكل من `job.id` و`job.workflow`. استطلع نقطة نهاية المهمة الخاصة بسير العمل حتى تصبح الحالة `completed` أو `failed`.

## حقول إنشاء المهمة

### التحويل

استخدم `workflow=conversion` لملف آلة تطريز موجود.

- مطلوب: `workflow` و`format` وإما `file` أو `files[]`
- الحد الأقصى لحجم المصدر: 50 ميجابايت لكل ملف
- يجب أن يكون تنسيق الإخراج `format` قابلاً للكتابة ومختلفاً عن تنسيق المصدر المكتشف.

### الرقمنة

استخدم `workflow=digitising` للأعمال الفنية بصيغ JPG أو JPEG أو PNG أو SVG أو WebP.

- مطلوب: `workflow` و`format` وإما `file` أو `files[]` و`width_mm` و`colour_count`
- `width_mm`: رقم من 10 إلى 300
- `colour_count`: عدد صحيح من 1 إلى 24
- الحد الأقصى لحجم المصدر: 20 ميجابايت لكل ملف

تقبل `files[]` حتى 10 مصادر في دفعة واحدة. قد تقتصر الحسابات ذات المعالجة المجانية المحدودة على مصدر واحد لكل طلب. تستخدم كل الملفات في الدفعة نفس سير العمل وصيغة الإخراج.

## استعلام حالة المهمة

```bash
curl https://embroideryfileconverter.com/api/developer/v1/jobs/conversion/01JEXAMPLEJOBID000000000 \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json"
```

الحالات المحتملة هي `queued` و`processing` و`completed` و`failed`. يحتوي رد المهمة المفصل على المقاييس والتحذيرات ومعلومات الفشل والأحداث والمعاينات والمخرجات وحالة الفتح وعناوين URL الموقعة المؤقتة للملفات. أعد طلب المهمة عند انتهاء صلاحية عنوان URL الموقع.

## مرجع نقاط النهاية الكامل

- يتطلب `GET /formats` الصلاحية `formats:read` ويعيد `data[]` بالإضافة إلى `artworkInputs[]`.
- يتطلب `GET /usage` الصلاحية `usage:read` ويعيد `freeUsage`، بما في ذلك الحصة والرصيد وتكاليف سير العمل وتواريخ إعادة التعيين.
- يتطلب `GET /jobs` الصلاحية `jobs:read` ويعيد `data[]` بالإضافة إلى `freeUsage` لما يصل إلى 50 مهمة مملوكة حديثة.
- يتطلب `POST /jobs` الصلاحية `jobs:write` وينشئ مهمة معاينة خاصة غير متزامنة واحدة أو أكثر.
- يتطلب `GET /jobs/conversion/{id}` الصلاحية `jobs:read` ويعيد مهمة تحويل مملوكة واحدة.
- يتطلب `GET /jobs/digitising/{id}` الصلاحية `jobs:read` ويعيد مهمة تحويل إلى غرز مملوكة واحدة.
- يتطلبان `POST /jobs/conversion/{id}/retry` و`POST /jobs/digitising/{id}/retry` الصلاحية `jobs:write`. يمكن إعادة محاولة المهام الفاشلة التي لا تزال مصادرها صالحة فقط.
- يتطلبان `POST /jobs/conversion/{id}/unlock` و`POST /jobs/digitising/{id}/unlock` الصلاحية `jobs:write`. يجب أن تكون المهمة مكتملة.
- تتطلب عناوين URL الموقعة `GET /uploads/{id}/download` و`GET /uploads/{id}/preview` الصلاحية `jobs:read`؛ استخدم عنوان URL الكامل المُعاد في رد المهمة بدلاً من إنشائه.

## سلوك فتح القفل

افحص `job.unlock` أو `GET /usage` قبل الفتح. قد يستهلك طلب الفتح استحقاق اشتراك متاح أو رصيد معالجة موجود في الحساب. قد تفتح الحسابات الداخلية بدون مقابل. لا يفتح عملية شراء أو شراء رصيد. يؤدي عدم كفاية الحصة أو الرصيد إلى خطأ تحقق.

## الأخطاء وسلوك إعادة المحاولة

- `401`: مفتاح المطور مفقود أو مشوه أو منتهي الصلاحية أو ملغى
- `403`: الصلاحية المطلوبة للمفتاح غير متوفرة أو المورد يخص حساباً آخر
- `404`: لم يُعثر على المهمة أو الملف الخاص
- `409`: حالة المهمة الحالية لا تسمح بإعادة المحاولة أو فتح القفل
- `410`: انتهت صلاحية رفع المصدر الخاص
- `422`: حقول غير صالحة أو ملف مصدر غير صالح أو صيغة إخراج غير مدعومة أو حصة غير كافية
- `429`: تم تجاوز حد معدل الطلبات؛ احترم `Retry-After` واستخدم التراجع الأسي مع التباين

تخضع إنشاء المهام أيضاً لحدود الرفع والمعالجة، وتخضع مسارات فتح القفل لحد أضيق لإجراءات الفوترة. تجنب الاستعلام المتكرر وتوقف بعد الوصول إلى حالة نهائية.

## نموذج الأمان

تبقى ملفات العملاء خاصة. يقتصر كل استعلام عن مهمة على مالك مفتاح API، وتنتهي صلاحية عناوين URL الموقعة، وتبقى ملفات الآلة القابلة للتنزيل مقفلة حتى اجتياز فحوصات الاستحقاق، وتُفرض صلاحيات المفتاح قبل تنفيذ العملية المطلوبة.

## الصفحات ذات الصلة

- [وكلاء الذكاء الاصطناعي وMCP](https://embroideryfileconverter.com/ar/ai-agents)
- [صيغ التطريز المدعومة](https://embroideryfileconverter.com/ar/formats)
- [الخصوصية والاحتفاظ بالملفات](https://embroideryfileconverter.com/ar/privacy)