# API de Programador do Conversor de Ficheiros de Bordado

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

Crie fluxos de trabalho de bordados com uma API REST privada para digitalização de imagens, conversão de ficheiros, estado de trabalhos, saídas validadas e transferências assinadas.

## Escolher a integração certa

- Utilize a API REST nesta página para um backend, produto SaaS, fluxo de trabalho de comércio eletrónico, automação ou aplicação do lado do servidor.
- Utilize a [documentação de agentes de IA e MCP](https://embroideryfileconverter.com/pt/ai-agents) quando um assistente deve agir em nome de um utilizador através de OAuth.

Não coloque uma chave de API de programador em JavaScript do navegador, numa aplicação móvel ou num binário de ambiente de trabalho distribuído.

## URL base e autenticação

- URL base: `https://embroideryfileconverter.com/api/developer/v1`
- Autenticação: `Authorization: Bearer efc_live_...`
- Tipo de conteúdo do trabalho: `multipart/form-data`
- Limite de taxa predefinido geral: 60 pedidos por minuto por chave, com um limite de rede separado
- Tempo de vida do URL de ficheiro assinado: 10 minutos
- [Descrição OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Criar ou revogar chaves de API](https://embroideryfileconverter.com/developers/keys)

As chaves de API são mostradas uma única vez, armazenadas apenas como hashes SHA-256, expiram e podem ser revogadas imediatamente. As capacidades disponíveis são `formats:read`, `usage:read`, `jobs:read` e `jobs:write`.

## Início rápido: criar um trabalho de conversão

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

A API devolve HTTP 202 porque o processamento é assíncrono:

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

Persista tanto `job.id` como `job.workflow`. Sondar o endpoint de trabalho específico do fluxo de trabalho até o estado passar a `completed` ou `failed`.

## Campos de criação de trabalho

### Conversão

Utilize `workflow=conversion` para um ficheiro de máquina de bordar existente.

- Obrigatório: `workflow`, `format` e `file` ou `files[]`
- Tamanho máximo da origem: 50 MB por ficheiro
- O `format` de saída tem de ser gravável e diferente do formato de origem detetado.

### Digitalização

Utilize `workflow=digitising` para arte JPG, JPEG, PNG, SVG ou WebP.

- Obrigatório: `workflow`, `format`, `file` ou `files[]`, `width_mm` e `colour_count`
- `width_mm`: número de 10 a 300
- `colour_count`: inteiro de 1 a 24
- Tamanho máximo da origem: 20 MB por ficheiro

`files[]` aceita até 10 origens num lote. Contas com processamento gratuito limitado podem ser restringidas a uma origem por pedido. Cada ficheiro num lote utiliza o mesmo fluxo de trabalho e formato de saída.

## Consultar um trabalho

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

Os estados possíveis são `queued`, `processing`, `completed` e `failed`. Uma resposta detalhada do trabalho contém métricas, avisos, informações de falha, eventos, artefactos de pré-visualização, saídas, estado de desbloqueio e URLs temporários assinados de ficheiros. Consulte o trabalho novamente quando um URL assinado expirar.

## Referência completa dos endpoints

- `GET /formats` requer `formats:read` e devolve `data[]` mais `artworkInputs[]`.
- `GET /usage` requer `usage:read` e devolve `freeUsage`, incluindo limite, créditos, custos de fluxo de trabalho e datas de reposição.
- `GET /jobs` requer `jobs:read` e devolve `data[]` mais `freeUsage` para até 50 trabalhos recentes da conta.
- `POST /jobs` requer `jobs:write` e cria um ou mais trabalhos de pré-visualização assíncronos privados.
- `GET /jobs/conversion/{id}` requer `jobs:read` e devolve um trabalho de conversão da conta.
- `GET /jobs/digitising/{id}` requer `jobs:read` e devolve um trabalho de digitalização da conta.
- `POST /jobs/conversion/{id}/retry` e `POST /jobs/digitising/{id}/retry` requerem `jobs:write`. Apenas trabalhos falhados com origem válida podem ser repetidos.
- `POST /jobs/conversion/{id}/unlock` e `POST /jobs/digitising/{id}/unlock` requerem `jobs:write`. O trabalho deve estar concluído.
- Os URLs assinados `GET /uploads/{id}/download` e `GET /uploads/{id}/preview` requerem `jobs:read`; utilize o URL completo devolvido na resposta do trabalho em vez de o construir.

## Comportamento de desbloqueio

Inspecione `job.unlock` ou `GET /usage` antes de desbloquear. Um pedido de desbloqueio pode consumir uma quota de subscrição disponível ou créditos de processamento já na conta. Contas internas podem desbloquear sem custo. Não abre checkout nem compra de créditos. Quota ou créditos insuficientes devolvem um erro de validação.

## Erros e comportamento de repetição

- `401`: chave de programador em falta, malformada, expirada ou revogada
- `403`: capacidade da chave em falta ou recurso pertence a outra conta
- `404`: trabalho ou ficheiro privado não encontrado
- `409`: o estado atual do trabalho não permite repetição ou desbloqueio
- `410`: o envio privado da origem expirou
- `422`: campos inválidos, ficheiro de origem, formato de saída ou quota insuficiente
- `429`: um limite de taxa foi excedido; respeite `Retry-After` e use backoff exponencial com jitter

A criação de trabalhos também está protegida por limites de envio e processamento; as rotas de desbloqueio têm um limite mais restrito de ações de faturação. Evite sondagens agressivas e pare após um estado terminal.

## Modelo de segurança

Os ficheiros dos clientes permanecem privados. Cada consulta de trabalho é restrita ao proprietário da chave de API, os URLs assinados expiram, os ficheiros de máquina descarregáveis permanecem bloqueados até os controlos de direitos passarem, e as capacidades da chave são aplicadas antes de a operação solicitada ser executada.

## Páginas relacionadas

- [Agentes de IA e MCP](https://embroideryfileconverter.com/pt/ai-agents)
- [Formatos de bordado suportados](https://embroideryfileconverter.com/pt/formats)
- [Privacidade e retenção de ficheiros](https://embroideryfileconverter.com/pt/privacy)