# Embroidery File Converter Developer API

Kanonisk sida: https://embroideryfileconverter.com/sv/developers

Bygg broderi-arbetsflöden med ett privat REST-API för bildigitalisering, filkonvertering, jobbstatus, validerade utdata och signerade nedladdningar.

## Välj rätt integration

- Använd REST-API:et på denna sida för en backend, SaaS-produkt, e-handelsflöde, automatisering eller server-side-applikation.
- Använd [AI-agent- och MCP-dokumentationen](https://embroideryfileconverter.com/sv/ai-agents) när en assistent ska agera på uppdrag av en användare via OAuth.

Placera inte en utvecklar-API-nyckel i webbläsar-JavaScript, en mobilapp eller en distribuerad desktop-binär.

## Bas-URL och autentisering

- Bas-URL: `https://embroideryfileconverter.com/api/developer/v1`
- Autentisering: `Authorization: Bearer efc_live_...`
- Jobbinnehållstyp: `multipart/form-data`
- Allmän standardhastighetsgräns: 60 förfrågningar per minut per nyckel, med ett separat nätverkstak
- Signerad fil-URL-livslängd: 10 minuter
- [OpenAPI 3.1-beskrivning](https://embroideryfileconverter.com/developers/openapi.json)
- [Skapa eller återkalla API-nycklar](https://embroideryfileconverter.com/developers/keys)

API-nycklar visas en gång, lagras endast som SHA-256-hashar, upphör att gälla och kan återkallas omedelbart. Tillgängliga förmågor är `formats:read`, `usage:read`, `jobs:read` och `jobs:write`.

## Snabbstart: skapa ett konverteringsjobb

```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:et returnerar HTTP 202 eftersom bearbetningen är asynkron:

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

Spara både `job.id` och `job.workflow`. Polla den arbetsflödesspecifika jobb-slutpunkten tills status blir `completed` eller `failed`.

## Fält för jobb-skapande

### Konvertering

Använd `workflow=conversion` för en befintlig broderimaskinsfil.

- Krävs: `workflow`, `format` och antingen `file` eller `files[]`
- Maximal källstorlek: 50 MB per fil
- Utdata-`format` måste vara skrivbart och skilja sig från det upptäckta källformatet.

### Digitalisering

Använd `workflow=digitising` för JPG-, JPEG-, PNG-, SVG- eller WebP-konstverk.

- Krävs: `workflow`, `format`, antingen `file` eller `files[]`, `width_mm` och `colour_count`
- `width_mm`: nummer från 10 till 300
- `colour_count`: heltal från 1 till 24
- Maximal källstorlek: 20 MB per fil

`files[]` accepterar upp till 10 källor i en batch. Konton med begränsad gratisbearbetning kan begränsas till en källa per begäran. Varje fil i en batch använder samma arbetsflöde och utdataformat.

## Poll a jobb

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

Möjliga statusar är `queued`, `processing`, `completed` och `failed`. Ett detaljerat jobbsvar innehåller mätvärden, varningar, felinformation, händelser, förhandsvisningsartefakter, utdata, upplåsningsstatus och tillfälliga signerade fil-URL:er. Begär jobbet igen när en signerad URL har gått ut.

## Fullständig slutpunktsreferens

- `GET /formats` kräver `formats:read` och returnerar `data[]` plus `artworkInputs[]`.
- `GET /usage` kräver `usage:read` och returnerar `freeUsage`, inklusive tilldelning, krediter, arbetsflödeskostnader och återställningsdatum.
- `GET /jobs` kräver `jobs:read` och returnerar `data[]` plus `freeUsage` för upp till 50 nyligen ägda jobb.
- `POST /jobs` kräver `jobs:write` och skapar ett eller flera privata asynkrona förhandsgranskningsjobb.
- `GET /jobs/conversion/{id}` kräver `jobs:read` och returnerar ett ägt konverteringsjobb.
- `GET /jobs/digitising/{id}` kräver `jobs:read` och returnerar ett ägt digitaliseringsjobb.
- `POST /jobs/conversion/{id}/retry` och `POST /jobs/digitising/{id}/retry` kräver `jobs:write`. Endast misslyckade jobb med en källa som inte har gått ut får göras om.
- `POST /jobs/conversion/{id}/unlock` och `POST /jobs/digitising/{id}/unlock` kräver `jobs:write`. Jobbet måste vara slutfört.
- Signerade `GET /uploads/{id}/download` och `GET /uploads/{id}/preview` URL:er kräver `jobs:read`; använd den fullständiga URL:en som returneras i jobbsvaret istället för att konstruera den.

## Upplåsningsbeteende

Inspektera `job.unlock` eller `GET /usage` innan upplåsning. En upplåsningsbegäran kan förbruka en tillgänglig prenumerationsrättighet eller bearbetningskrediter som redan finns på kontot. Interna konton kan låsa upp utan kostnad. Det öppnar inte kassa eller köp av krediter. Otillräcklig kvot eller krediter returnerar ett valideringsfel.

## Fel och omförsöksbeteende

- `401`: saknad, felaktig, utgången eller återkallad utvecklarnyckel
- `403`: saknad nyckelbehörighet eller resurs tillhör ett annat konto
- `404`: jobb eller privat fil hittades inte
- `409`: jobbets aktuella tillstånd tillåter inte omförsök eller upplåsning
- `410`: den privata källuppladdningen har gått ut
- `422`: ogiltiga fält, källfil, utdataformat eller otillräcklig kvot
- `429`: en hastighetsgräns överskreds; respektera `Retry-After` och använd exponentiell backoff med jitter

Jobbskapande skyddas också av uppladdnings- och bearbetningsgränser, och upplåsningsvägar har en stramare faktureringsgräns. Undvik aggressiv polling och stoppa efter en terminal status.

## Säkerhetsmodell

Kundfiler förblir privata. Varje jobbfråga är begränsad till API-nyckelns ägare, signerade URL:er går ut, nedladdningsbara maskinfiler förblir låsta tills behörighetskontroller godkänns, och nyckelbehörigheter tillämpas innan den begärda åtgärden utförs.

## Relaterade sidor

- [AI-agenter och MCP](https://embroideryfileconverter.com/sv/ai-agents)
- [Stödda broderiformat](https://embroideryfileconverter.com/sv/formats)
- [Integritet och filbevarande](https://embroideryfileconverter.com/sv/privacy)