# Embroidery File Converter Developer API

Canonieke pagina: https://embroideryfileconverter.com/nl/developers

Bouw borduurworkflows met een privé REST-API voor beelddigitalisering, bestandsconversie, jobstatus, gevalideerde uitvoer en ondertekende downloads.

## Kies de juiste integratie

- Gebruik de REST API op deze pagina voor een backend, SaaS-product, e-commerce-workflow, automatisering of server-side applicatie.
- Gebruik de [AI-agent- en MCP-documentatie](https://embroideryfileconverter.com/nl/ai-agents) wanneer een assistent namens een gebruiker moet handelen via OAuth.

Plaats geen developer API-sleutel in browser-JavaScript, een mobiele app of een gedistribueerde desktop-binary.

## Base-URL en authenticatie

- Basis-URL: `https://embroideryfileconverter.com/api/developer/v1`
- Authenticatie: `Authorization: Bearer efc_live_...`
- Job-contenttype: `multipart/form-data`
- Algemene standaard rate limit: 60 verzoeken per minuut per sleutel, met een apart netwerkplafond
- Levensduur van ondertekende file-URL: 10 minuten
- [OpenAPI 3.1-beschrijving](https://embroideryfileconverter.com/developers/openapi.json)
- [API-sleutels maken of intrekken](https://embroideryfileconverter.com/developers/keys)

API-sleutels worden eenmaal getoond, alleen als SHA-256-hashes opgeslagen, verlopen en kunnen direct worden ingetrokken. Beschikbare abilities zijn `formats:read`, `usage:read`, `jobs:read` en `jobs:write`.

## Quickstart: conversie-job maken

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

De API retourneert HTTP 202 omdat verwerking asynchroon is:

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

Bewaar zowel `job.id` als `job.workflow`. Poll het workflow-specifieke job-endpoint tot de status `completed` of `failed` wordt.

## Job-creatievelden

### Conversie

Gebruik `workflow=conversion` voor een bestaand borduurmachinebestand.

- Vereist: `workflow`, `format` en `file` of `files[]`
- Maximale brongrootte: 50 MB per bestand
- Het uitvoer-`format` moet schrijfbaar zijn en verschillen van het gedetecteerde bronformaat.

### Digitaliseren

Gebruik `workflow=digitising` voor JPG-, JPEG-, PNG-, SVG- of WebP-artwork.

- Vereist: `workflow`, `format`, `file` of `files[]`, `width_mm` en `colour_count`
- `width_mm`: getal van 10 tot en met 300
- `colour_count`: integer van 1 tot en met 24
- Maximale brongrootte: 20 MB per bestand

`files[]` accepteert maximaal 10 bronnen per batch. Accounts met beperkt gratis verwerken kunnen beperkt zijn tot één bron per aanvraag. Elk bestand in een batch gebruikt dezelfde workflow en uitvoerindeling.

## Taak opvragen

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

Mogelijke statussen zijn `queued`, `processing`, `completed` en `failed`. Een gedetailleerde taakreactie bevat statistieken, waarschuwingen, foutinformatie, gebeurtenissen, voorbeeldartefacten, uitvoer, ontgrendelstatus en tijdelijke ondertekende bestands-URL's. Vraag de taak opnieuw op wanneer een ondertekende URL verloopt.

## Volledige endpoint-referentie

- `GET /formats` vereist `formats:read` en retourneert `data[]` plus `artworkInputs[]`.
- `GET /usage` vereist `usage:read` en retourneert `freeUsage`, inclusief tegoed, credits, workflowkosten en resetdatums.
- `GET /jobs` vereist `jobs:read` en retourneert `data[]` plus `freeUsage` voor maximaal 50 recente eigen taken.
- `POST /jobs` vereist `jobs:write` en maakt één of meer privé asynchrone voorbeeldtaken.
- `GET /jobs/conversion/{id}` vereist `jobs:read` en retourneert één eigen conversietaak.
- `GET /jobs/digitising/{id}` vereist `jobs:read` en retourneert één eigen digitaliseertaak.
- `POST /jobs/conversion/{id}/retry` en `POST /jobs/digitising/{id}/retry` vereisen `jobs:write`. Alleen mislukte taken met een niet-verlopen bron mogen opnieuw worden geprobeerd.
- `POST /jobs/conversion/{id}/unlock` en `POST /jobs/digitising/{id}/unlock` vereisen `jobs:write`. De taak moet voltooid zijn.
- Ondertekende `GET /uploads/{id}/download` en `GET /uploads/{id}/preview` URL's vereisen `jobs:read`; gebruik de volledige URL uit de taakreactie in plaats van deze zelf samen te stellen.

## Ontgrendelgedrag

Controleer `job.unlock` of `GET /usage` voordat u ontgrendelt. Een ontgrendelingsverzoek kan een beschikbaar abonnementsrecht of reeds aanwezige verwerkingscredits verbruiken. Interne accounts kunnen mogelijk gratis ontgrendelen. Het opent geen afrekenpagina of aankoop van credits. Onvoldoende quota of credits resulteert in een validatiefout.

## Fouten en opnieuw proberen

- `401`: ontbrekende, ongeldige, verlopen of ingetrokken ontwikkelaarsleutel
- `403`: ontbrekend sleutelrecht of resource behoort tot een ander account
- `404`: taak of privébestand niet gevonden
- `409`: de huidige taakstatus staat retry of unlock niet toe
- `410`: de privébronupload is verlopen
- `422`: ongeldige velden, bronbestand, uitvoerindeling of onvoldoende quota
- `429`: een ratelimit is overschreden; respecteer `Retry-After` en gebruik exponential backoff met jitter

Taakcreatie wordt ook beschermd door upload- en verwerkingslimieten, en unlock-routes hebben een strengere factureringslimiet. Vermijd agressief pollen en stop na een terminale status.

## Beveiligingsmodel

Klantbestanden blijven privé. Elke taakquery is beperkt tot de eigenaar van de API-sleutel, ondertekende URL's verlopen, downloadbare machinebestanden blijven vergrendeld tot rechtencontroles slagen, en sleutelrechten worden afgedwongen voordat de gevraagde bewerking wordt uitgevoerd.

## Gerelateerde pagina's

- [AI-agenten en MCP](https://embroideryfileconverter.com/nl/ai-agents)
- [Ondersteunde borduurindelingen](https://embroideryfileconverter.com/nl/formats)
- [Privacy en bestandsbewaring](https://embroideryfileconverter.com/nl/privacy)