# API per sviluppatori Embroidery File Converter

Pagina canonica: https://embroideryfileconverter.com/it/developers

Crea flussi di lavoro per ricamo con un'API REST privata per digitalizzazione immagini, conversione file, stato lavori, output convalidati e download firmati.

## Scegli l’integrazione giusta

- Usa l’API REST su questa pagina per un backend, un prodotto SaaS, un flusso ecommerce, automazione o un’applicazione lato server.
- Usa la [documentazione agenti IA e MCP](https://embroideryfileconverter.com/it/ai-agents) quando un assistente deve agire per conto di un utente tramite OAuth.

Non inserire una chiave API sviluppatore in JavaScript del browser, in un’applicazione mobile o in un binario desktop distribuito.

## URL base e autenticazione

- URL di base: `https://embroideryfileconverter.com/api/developer/v1`
- Autenticazione: `Authorization: Bearer efc_live_...`
- Tipo di contenuto del lavoro: `multipart/form-data`
- Limite di velocità predefinito generale: 60 richieste al minuto per chiave, con un tetto di rete separato
- Durata URL file firmato: 10 minuti
- [Descrizione OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Crea o revoca chiavi API](https://embroideryfileconverter.com/developers/keys)

Le chiavi API vengono mostrate una sola volta, archiviate solo come hash SHA-256, scadono e possono essere revocate immediatamente. Le abilità disponibili sono `formats:read`, `usage:read`, `jobs:read` e `jobs:write`.

## Avvio rapido: crea un lavoro di conversione

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

L’API restituisce HTTP 202 perché l’elaborazione è asincrona:

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

Conserva sia `job.id` sia `job.workflow`. Interroga l’endpoint del lavoro specifico del flusso finché lo stato non diventa `completed` o `failed`.

## Campi di creazione del lavoro

### Conversione

Usa `workflow=conversion` per un file macchina da ricamo esistente.

- Obbligatori: `workflow`, `format` e `file` o `files[]`
- Dimensione massima sorgente: 50 MB per file
- Il `format` di output deve essere scrivibile e diverso dal formato sorgente rilevato.

### Digitalizzazione

Usa `workflow=digitising` per artwork JPG, JPEG, PNG, SVG o WebP.

- Obbligatori: `workflow`, `format`, `file` o `files[]`, `width_mm` e `colour_count`
- `width_mm`: numero da 10 a 300
- `colour_count`: intero da 1 a 24
- Dimensione massima sorgente: 20 MB per file

`files[]` accetta fino a 10 origini in un unico batch. Gli account con elaborazione gratuita limitata possono essere vincolati a una sola origine per richiesta. Ogni file di un batch utilizza lo stesso flusso di lavoro e formato di output.

## Interroga un lavoro

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

Gli stati possibili sono `queued`, `processing`, `completed` e `failed`. Una risposta dettagliata del lavoro contiene metriche, avvisi, informazioni sugli errori, eventi, anteprime, output, stato di sblocco e URL temporanei firmati dei file. Richiedi di nuovo il lavoro quando un URL firmato scade.

## Riferimento completo degli endpoint

- `GET /formats` richiede `formats:read` e restituisce `data[]` più `artworkInputs[]`.
- `GET /usage` richiede `usage:read` e restituisce `freeUsage`, inclusi crediti disponibili, crediti, costi dei flussi di lavoro e date di azzeramento.
- `GET /jobs` richiede `jobs:read` e restituisce `data[]` più `freeUsage` per un massimo di 50 lavori recenti dell’utente.
- `POST /jobs` richiede `jobs:write` e crea uno o più lavori di anteprima asincroni privati.
- `GET /jobs/conversion/{id}` richiede `jobs:read` e restituisce un lavoro di conversione dell’utente.
- `GET /jobs/digitising/{id}` richiede `jobs:read` e restituisce un lavoro di digitalizzazione dell’utente.
- `POST /jobs/conversion/{id}/retry` e `POST /jobs/digitising/{id}/retry` richiedono `jobs:write`. Solo i lavori non riusciti con origine ancora valida possono essere ritentati.
- `POST /jobs/conversion/{id}/unlock` e `POST /jobs/digitising/{id}/unlock` richiedono `jobs:write`. Il lavoro deve essere completato.
- Gli URL firmati `GET /uploads/{id}/download` e `GET /uploads/{id}/preview` richiedono `jobs:read`; utilizza l’URL completo restituito nella risposta del lavoro invece di ricostruirlo.

## Comportamento di sblocco

Ispeziona `job.unlock` o `GET /usage` prima dello sblocco. Una richiesta di sblocco può consumare un diritto di abbonamento disponibile o crediti di elaborazione già presenti sull'account. Gli account interni possono sbloccare senza costi. Non apre checkout né acquisto di crediti. Quota o crediti insufficienti restituiscono un errore di convalida.

## Errori e comportamento di ripetizione

- `401`: chiave sviluppatore mancante, non valida, scaduta o revocata
- `403`: autorizzazione della chiave mancante o risorsa appartenente a un altro account
- `404`: lavoro o file privato non trovato
- `409`: lo stato attuale del lavoro non consente ripetizione o sblocco
- `410`: l’upload dell’origine privata è scaduto
- `422`: campi non validi, file di origine, formato di output o quota insufficiente
- `429`: limite di frequenza superato; rispetta `Retry-After` e utilizza backoff esponenziale con jitter

La creazione di lavori è protetta anche da limiti di upload ed elaborazione; le route di sblocco hanno un limite più stretto sulle azioni di fatturazione. Evita polling aggressivi e interrompi dopo uno stato terminale.

## Modello di sicurezza

I file del cliente restano privati. Ogni query di lavoro è limitata al proprietario della chiave API, gli URL firmati scadono, i file macchina scaricabili restano bloccati finché non superano i controlli dei diritti e le autorizzazioni della chiave vengono verificate prima dell’esecuzione dell’operazione richiesta.

## Pagine correlate

- [Agenti IA e MCP](https://embroideryfileconverter.com/it/ai-agents)
- [Formati di ricamo supportati](https://embroideryfileconverter.com/it/formats)
- [Privacy e conservazione dei file](https://embroideryfileconverter.com/it/privacy)