# Embroidery File Converter Developer API

דף קנוני: https://embroideryfileconverter.com/he/developers

בנה זרימות עבודה לרקמה עם REST API פרטי לדיגיטציית תמונות, המרת קבצים, סטטוס עבודות, פלטים מאומתים והורדות חתומות.

## בחר את האינטגרציה הנכונה

- השתמש ב-REST API בדף זה עבור backend, מוצר SaaS, תהליך מסחר אלקטרוני, אוטומציה או יישום בצד השרת.
- השתמש ב[תיעוד סוכני AI ו-MCP](https://embroideryfileconverter.com/he/ai-agents) כאשר עוזר צריך לפעול בשם משתמש דרך OAuth.

אל תשים מפתח API של מפתח ב-JavaScript של דפדפן, באפליקציה ניידת או בקובץ בינארי שולחני מפוזר.

## כתובת בסיס ואימות

- כתובת בסיס: `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 מוצגים פעם אחת, מאוחסנים רק כ-hash של 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 MB לקובץ
- פורמט הפלט `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 MB לקובץ

`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` והשתמש ב-backoff מעריכי עם jitter

יצירת משימות מוגנת גם על ידי מגבלות העלאה ועיבוד, ומסלולי ביטול נעילה כפופים למגבלת פעולת חיוב הדוקה יותר. הימנע מסקרים אגרסיביים והפסק לאחר סטטוס סופי.

## מודל אבטחה

קובצי הלקוח נשארים פרטיים. כל שאילתת משימה מוגבלת לבעל מפתח ה-API, כתובות URL חתומות פוקעות, קובצי מכונה להורדה נשארים נעולים עד שמעבר בדיקות זכאות, ויכולות המפתח נאכפות לפני ביצוע הפעולה המבוקשת.

## דפים קשורים

- [סוכני AI ו-MCP](https://embroideryfileconverter.com/he/ai-agents)
- [פורמטי רקמה נתמכים](https://embroideryfileconverter.com/he/formats)
- [פרטיות ושמירת קבצים](https://embroideryfileconverter.com/he/privacy)