# API de desarrollador del Convertidor de archivos de bordado

Página canónica: https://embroideryfileconverter.com/es/developers

Cree flujos de trabajo de bordado con una API REST privada para digitalización de imágenes, conversión de archivos, estado de trabajos, salidas validadas y descargas firmadas.

## Elegir la integración correcta

- Utilice la API REST de esta página para un backend, un producto SaaS, un flujo de trabajo de comercio electrónico, automatización o una aplicación del lado del servidor.
- Utilice la [documentación de agentes de IA y MCP](https://embroideryfileconverter.com/es/ai-agents) cuando un asistente deba actuar en nombre de un usuario mediante OAuth.

No coloque una clave API de desarrollador en JavaScript del navegador, una aplicación móvil ni un binario de escritorio distribuido.

## URL base y autenticación

- URL base: `https://embroideryfileconverter.com/api/developer/v1`
- Autenticación: `Authorization: Bearer efc_live_...`
- Tipo de contenido del trabajo: `multipart/form-data`
- Límite de velocidad predeterminado general: 60 solicitudes por minuto por clave, con un techo de red independiente
- Tiempo de vida de la URL de archivo firmada: 10 minutos
- [Descripción OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Crear o revocar claves API](https://embroideryfileconverter.com/developers/keys)

Las claves API se muestran una sola vez, se almacenan únicamente como hashes SHA-256, caducan y pueden revocarse inmediatamente. Las capacidades disponibles son `formats:read`, `usage:read`, `jobs:read` y `jobs:write`.

## Inicio rápido: crear un trabajo de conversión

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

La API devuelve HTTP 202 porque el procesamiento es asíncrono:

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

Conserve tanto `job.id` como `job.workflow`. Sondee el endpoint de trabajo específico del flujo hasta que el estado sea `completed` o `failed`.

## Campos de creación de trabajos

### Conversión

Utilice `workflow=conversion` para un archivo de máquina de bordado existente.

- Obligatorio: `workflow`, `format` y `file` o `files[]`
- Tamaño máximo de origen: 50 MB por archivo
- El `format` de salida debe ser grabable y diferente del formato de origen detectado.

### Digitización

Utilice `workflow=digitising` para ilustraciones JPG, JPEG, PNG, SVG o WebP.

- Obligatorio: `workflow`, `format`, `file` o `files[]`, `width_mm` y `colour_count`
- `width_mm`: número entre 10 y 300
- `colour_count`: entero del 1 al 24
- Tamaño máximo de origen: 20 MB por archivo

`files[]` acepta hasta 10 orígenes en un lote. Las cuentas con procesamiento gratuito limitado pueden estar restringidas a un origen por solicitud. Cada archivo en un lote utiliza el mismo flujo de trabajo y formato de salida.

## Consultar un trabajo

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

Los estados posibles son `queued`, `processing`, `completed` y `failed`. Una respuesta detallada del trabajo contiene métricas, advertencias, información de fallos, eventos, artefactos de vista previa, salidas, estado de desbloqueo y URL temporales firmadas de archivos. Vuelva a solicitar el trabajo cuando expire una URL firmada.

## Referencia completa de puntos finales

- `GET /formats` requiere `formats:read` y devuelve `data[]` más `artworkInputs[]`.
- `GET /usage` requiere `usage:read` y devuelve `freeUsage`, incluyendo asignación, créditos, costos de flujo de trabajo y fechas de restablecimiento.
- `GET /jobs` requiere `jobs:read` y devuelve `data[]` más `freeUsage` para hasta 50 trabajos recientes propios.
- `POST /jobs` requiere `jobs:write` y crea uno o más trabajos de vista previa asíncronos privados.
- `GET /jobs/conversion/{id}` requiere `jobs:read` y devuelve un trabajo de conversión propio.
- `GET /jobs/digitising/{id}` requiere `jobs:read` y devuelve un trabajo de digitalización propio.
- `POST /jobs/conversion/{id}/retry` y `POST /jobs/digitising/{id}/retry` requieren `jobs:write`. Solo pueden reintentarse trabajos fallidos con un origen no expirado.
- `POST /jobs/conversion/{id}/unlock` y `POST /jobs/digitising/{id}/unlock` requieren `jobs:write`. El trabajo debe estar completado.
- Las URL firmadas `GET /uploads/{id}/download` y `GET /uploads/{id}/preview` requieren `jobs:read`; utilice la URL completa devuelta en la respuesta del trabajo en lugar de construirla.

## Comportamiento de desbloqueo

Inspecciona `job.unlock` o `GET /usage` antes de desbloquear. Una solicitud de desbloqueo puede consumir un derecho de suscripción disponible o créditos de procesamiento ya en la cuenta. Las cuentas internas pueden desbloquear sin cargo. No abre checkout ni compra de créditos. La cuota o créditos insuficientes devuelven un error de validación.

## Errores y comportamiento de reintento

- `401`: clave de desarrollador ausente, mal formada, expirada o revocada
- `403`: capacidad de clave ausente o recurso pertenece a otra cuenta
- `404`: trabajo o archivo privado no encontrado
- `409`: el estado actual del trabajo no permite reintento ni desbloqueo
- `410`: el origen privado cargado expiró
- `422`: campos no válidos, archivo de origen, formato de salida o cuota insuficiente
- `429`: se superó un límite de velocidad; respete `Retry-After` y utilice retroceso exponencial con fluctuación

La creación de trabajos también está protegida por límites de carga y procesamiento, y las rutas de desbloqueo tienen un límite más estricto de acciones de facturación. Evite sondeos agresivos y deténgase tras un estado terminal.

## Modelo de seguridad

Los archivos del cliente permanecen privados. Cada consulta de trabajo está restringida al propietario de la clave API, las URL firmadas expiran, los archivos de máquina descargables permanecen bloqueados hasta que pasen las comprobaciones de derechos y las capacidades de la clave se aplican antes de ejecutar la operación solicitada.

## Páginas relacionadas

- [Agentes de IA y MCP](https://embroideryfileconverter.com/es/ai-agents)
- [Formatos de bordado compatibles](https://embroideryfileconverter.com/es/formats)
- [Privacidad y retención de archivos](https://embroideryfileconverter.com/es/privacy)