# Embroidery File Converter Developer API

Kanonische Seite: https://embroideryfileconverter.com/de/developers

Erstellen Sie Stickworkflows mit einer privaten REST-API für Bild-Digitalisierung, Dateikonvertierung, Auftragsstatus, validierte Ausgaben und signierte Downloads.

## Richtige Integration auswählen

- Die REST-API auf dieser Seite für ein Backend, SaaS-Produkt, E-Commerce-Workflow, Automatisierung oder serverseitige Anwendung verwenden.
- Die [KI-Agenten- und MCP-Dokumentation](https://embroideryfileconverter.com/de/ai-agents) verwenden, wenn ein Assistent im Namen eines Benutzers über OAuth handeln soll.

Entwickler-API-Schlüssel nicht in Browser-JavaScript, einer mobilen Anwendung oder einer verteilten Desktop-Binärdatei ablegen.

## Basis-URL und Authentifizierung

- Basis-URL: `https://embroideryfileconverter.com/api/developer/v1`
- Authentifizierung: `Authorization: Bearer efc_live_...`
- Auftragsinhaltstyp: `multipart/form-data`
- Allgemeines Standard-Ratenlimit: 60 Anfragen pro Minute pro Schlüssel, mit separater Netzwerkobergrenze
- Lebensdauer signierter Datei-URLs: 10 Minuten
- [OpenAPI-3.1-Beschreibung](https://embroideryfileconverter.com/developers/openapi.json)
- [API-Schlüssel erstellen oder widerrufen](https://embroideryfileconverter.com/developers/keys)

API-Schlüssel werden einmal angezeigt, nur als SHA-256-Hashes gespeichert, laufen ab und können sofort widerrufen werden. Verfügbare Berechtigungen sind `formats:read`, `usage:read`, `jobs:read` und `jobs:write`.

## Schnellstart: Konvertierungsauftrag erstellen

```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"
```

Die API gibt HTTP 202 zurück, weil die Verarbeitung asynchron erfolgt:

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

Sowohl `job.id` als auch `job.workflow` persistieren. Workflow-spezifischen Job-Endpunkt abfragen, bis Status `completed` oder `failed` lautet.

## Felder zur Auftragserstellung

### Konvertierung

`workflow=conversion` für eine vorhandene Stickmaschinendatei verwenden.

- Erforderlich: `workflow`, `format` und entweder `file` oder `files[]`
- Maximale Quellgröße: 50 MB pro Datei
- Das Ausgabe-`format` muss schreibbar und vom erkannten Quellformat verschieden sein.

### Digitalisieren

`workflow=digitising` für JPG-, JPEG-, PNG-, SVG- oder WebP-Vorlagen verwenden.

- Erforderlich: `workflow`, `format`, entweder `file` oder `files[]`, `width_mm` und `colour_count`
- `width_mm`: Zahl von 10 bis 300
- `colour_count`: Ganzzahl von 1 bis 24
- Maximale Quellgröße: 20 MB pro Datei

`files[]` akzeptiert bis zu 10 Quellen in einem Stapel. Konten mit eingeschränkter kostenloser Verarbeitung können auf eine Quelle pro Anfrage beschränkt sein. Jede Datei eines Stapels verwendet denselben Workflow und Ausgabeformat.

## Auftrag abfragen

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

Mögliche Status sind `queued`, `processing`, `completed` und `failed`. Eine detaillierte Auftragsantwort enthält Metriken, Warnungen, Fehlerinformationen, Ereignisse, Vorschau-Artefakte, Ausgaben, Entsperrstatus und temporäre signierte Datei-URLs. Fordern Sie den Auftrag erneut an, wenn eine signierte URL abläuft.

## Vollständige Endpunkt-Referenz

- `GET /formats` erfordert `formats:read` und liefert `data[]` sowie `artworkInputs[]`.
- `GET /usage` erfordert `usage:read` und liefert `freeUsage`, einschließlich Guthaben, Credits, Workflow-Kosten und Zurücksetzungsdaten.
- `GET /jobs` erfordert `jobs:read` und liefert `data[]` sowie `freeUsage` für bis zu 50 aktuelle eigene Aufträge.
- `POST /jobs` erfordert `jobs:write` und erstellt einen oder mehrere private asynchrone Vorschau-Aufträge.
- `GET /jobs/conversion/{id}` erfordert `jobs:read` und liefert einen eigenen Konvertierungsauftrag.
- `GET /jobs/digitising/{id}` erfordert `jobs:read` und liefert einen eigenen Digitalisierungsauftrag.
- `POST /jobs/conversion/{id}/retry` und `POST /jobs/digitising/{id}/retry` erfordern `jobs:write`. Nur fehlgeschlagene Aufträge mit noch gültiger Quelle können erneut versucht werden.
- `POST /jobs/conversion/{id}/unlock` und `POST /jobs/digitising/{id}/unlock` erfordern `jobs:write`. Der Auftrag muss abgeschlossen sein.
- Signierte `GET /uploads/{id}/download`- und `GET /uploads/{id}/preview`-URLs erfordern `jobs:read`; verwenden Sie die vollständige URL aus der Auftragsantwort, anstatt sie selbst zu erstellen.

## Entsperrverhalten

Prüfen Sie `job.unlock` oder `GET /usage` vor dem Freischalten. Eine Freischaltanfrage kann ein verfügbares Abonnement-Recht oder bereits auf dem Konto vorhandene Verarbeitungs-Credits verbrauchen. Interne Konten können kostenlos freischalten. Es öffnet keinen Checkout und kauft keine Credits. Unzureichendes Kontingent oder Credits gibt einen Validierungsfehler zurück.

## Fehler- und Wiederholungsverhalten

- `401`: fehlender, fehlerhafter, abgelaufener oder widerrufener Entwicklerschlüssel
- `403`: fehlende Schlüsselberechtigung oder Ressource gehört einem anderen Konto
- `404`: Auftrag oder private Datei wurde nicht gefunden
- `409`: der aktuelle Auftragsstatus erlaubt kein Wiederholen oder Entsperren
- `410`: der private Quell-Upload ist abgelaufen
- `422`: ungültige Felder, Quelldatei, Ausgabeformat oder unzureichendes Kontingent
- `429`: ein Ratenlimit wurde überschritten; beachten Sie `Retry-After` und verwenden Sie exponentielles Backoff mit Jitter

Die Auftragserstellung ist ebenfalls durch Upload- und Verarbeitungslimits geschützt, und Entsperr-Routen haben ein strengeres Abrechnungsaktionslimit. Vermeiden Sie aggressives Polling und stoppen Sie nach einem Endstatus.

## Sicherheitsmodell

Kundendateien bleiben privat. Jede Auftragsabfrage ist auf den API-Schlüssel-Besitzer beschränkt, signierte URLs laufen ab, herunterladbare Maschinendateien bleiben gesperrt, bis Berechtigungsprüfungen bestanden sind, und Schlüsselberechtigungen werden vor Ausführung der angeforderten Operation erzwungen.

## Verwandte Seiten

- [KI-Agenten und MCP](https://embroideryfileconverter.com/de/ai-agents)
- [Unterstützte Stickformate](https://embroideryfileconverter.com/de/formats)
- [Datenschutz und Dateiaufbewahrung](https://embroideryfileconverter.com/de/privacy)