# API de développement du convertisseur de fichiers de broderie

Page canonique: https://embroideryfileconverter.com/fr/developers

Construisez des workflows de broderie avec une API REST privée pour la numérisation d'image, la conversion de fichiers, le statut des travaux, les sorties validées et les téléchargements signés.

## Choisir la bonne intégration

- Utiliser l’API REST de cette page pour un backend, un produit SaaS, un flux e-commerce, une automatisation ou une application côté serveur.
- Utiliser la [documentation agent IA et MCP](https://embroideryfileconverter.com/fr/ai-agents) lorsqu’un assistant doit agir au nom d’un utilisateur via OAuth.

Ne pas placer une clé API développeur dans du JavaScript navigateur, une application mobile ou un binaire de bureau distribué.

## URL de base et authentification

- URL de base: `https://embroideryfileconverter.com/api/developer/v1`
- Authentification: `Authorization: Bearer efc_live_...`
- Type de contenu du travail: `multipart/form-data`
- Limite de débit générale par défaut : 60 requêtes par minute par clé, avec un plafond réseau distinct
- Durée de vie de l’URL de fichier signée : 10 minutes
- [Description OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Créer ou révoquer des clés API](https://embroideryfileconverter.com/developers/keys)

Les clés API sont affichées une seule fois, stockées uniquement sous forme de hachages SHA-256, expirent et peuvent être révoquées immédiatement. Les capacités disponibles sont `formats:read`, `usage:read`, `jobs:read` et `jobs:write`.

## Démarrage rapide : créer un travail de conversion

```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 renvoie HTTP 202 car le traitement est asynchrone :

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

Conserver à la fois `job.id` et `job.workflow`. Sonder le point de terminaison du travail spécifique au workflow jusqu’à ce que le statut devienne `completed` ou `failed`.

## Champs de création de travail

### Conversion

Utiliser `workflow=conversion` pour un fichier machine de broderie existant.

- Obligatoire : `workflow`, `format` et `file` ou `files[]`
- Taille source maximale : 50 Mo par fichier
- Le `format` de sortie doit être inscriptible et différent du format source détecté.

### Numérisation

Utiliser `workflow=digitising` pour une illustration JPG, JPEG, PNG, SVG ou WebP.

- Obligatoire : `workflow`, `format`, `file` ou `files[]`, `width_mm` et `colour_count`
- `width_mm` : nombre de 10 à 300
- `colour_count` : entier de 1 à 24
- Taille source maximale : 20 Mo par fichier

`files[]` accepte jusqu’à 10 sources par lot. Les comptes soumis à un traitement gratuit limité peuvent être restreints à une source par requête. Chaque fichier d’un lot utilise le même workflow et le même format de sortie.

## Interroger un job

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

Les statuts possibles sont `queued`, `processing`, `completed` et `failed`. Une réponse détaillée de job contient des métriques, des avertissements, des informations d’échec, des événements, des artefacts d’aperçu, des sorties, l’état de déverrouillage et des URL temporaires signées de fichiers. Interrogez à nouveau le job lorsqu’une URL signée expire.

## Référence complète des points de terminaison

- `GET /formats` nécessite `formats:read` et renvoie `data[]` ainsi que `artworkInputs[]`.
- `GET /usage` nécessite `usage:read` et renvoie `freeUsage`, y compris le quota, les crédits, les coûts de workflow et les dates de réinitialisation.
- `GET /jobs` nécessite `jobs:read` et renvoie `data[]` ainsi que `freeUsage` pour un maximum de 50 jobs récents appartenant au compte.
- `POST /jobs` nécessite `jobs:write` et crée un ou plusieurs jobs d’aperçu asynchrones privés.
- `GET /jobs/conversion/{id}` nécessite `jobs:read` et renvoie un job de conversion appartenant au compte.
- `GET /jobs/digitising/{id}` nécessite `jobs:read` et renvoie un job de numérisation appartenant au compte.
- `POST /jobs/conversion/{id}/retry` et `POST /jobs/digitising/{id}/retry` nécessitent `jobs:write`. Seuls les jobs en échec dont la source n’a pas expiré peuvent être relancés.
- `POST /jobs/conversion/{id}/unlock` et `POST /jobs/digitising/{id}/unlock` nécessitent `jobs:write`. Le job doit être terminé.
- Les URL signées `GET /uploads/{id}/download` et `GET /uploads/{id}/preview` nécessitent `jobs:read` ; utilisez l’URL complète renvoyée dans la réponse du job plutôt que de la construire.

## Comportement de déverrouillage

Inspectez `job.unlock` ou `GET /usage` avant déverrouillage. Une demande de déverrouillage peut consommer un droit d’abonnement disponible ou des crédits de traitement déjà présents sur le compte. Les comptes internes peuvent déverrouiller gratuitement. Cela n’ouvre pas de paiement ni d’achat de crédits. Un quota ou des crédits insuffisants renvoie une erreur de validation.

## Erreurs et comportement de relance

- `401` : clé de développeur manquante, mal formée, expirée ou révoquée
- `403` : capacité de clé manquante ou ressource appartenant à un autre compte
- `404` : job ou fichier privé introuvable
- `409` : l’état actuel du job n’autorise pas la relance ou le déverrouillage
- `410` : le téléversement de la source privée a expiré
- `422` : champs, fichier source, format de sortie invalides ou quota insuffisant
- `429` : une limite de débit a été dépassée ; respectez `Retry-After` et utilisez un backoff exponentiel avec jitter

La création de jobs est également protégée par des limites de téléversement et de traitement, et les routes de déverrouillage ont une limite d’action de facturation plus stricte. Évitez les interrogations agressives et arrêtez après un statut terminal.

## Modèle de sécurité

Les fichiers des clients restent privés. Chaque requête de job est limitée au propriétaire de la clé API, les URL signées expirent, les fichiers machine téléchargeables restent verrouillés jusqu’à validation des droits, et les capacités de la clé sont vérifiées avant l’exécution de l’opération demandée.

## Pages associées

- [Agents IA et MCP](https://embroideryfileconverter.com/fr/ai-agents)
- [Formats de broderie pris en charge](https://embroideryfileconverter.com/fr/formats)
- [Confidentialité et conservation des fichiers](https://embroideryfileconverter.com/fr/privacy)