# API deweloperskie Konwertera Plików Haftu

Strona kanoniczna: https://embroideryfileconverter.com/pl/developers

Twórz workflow haftu za pomocą prywatnego REST API do digitalizacji obrazów, konwersji plików, statusu zadań, zweryfikowanych wyników i podpisanych pobrań.

## Wybierz właściwą integrację

- Użyj REST API na tej stronie dla backendu, produktu SaaS, przepływu e-commerce, automatyzacji lub aplikacji po stronie serwera.
- Użyj [dokumentacji agenta AI i MCP](https://embroideryfileconverter.com/pl/ai-agents), gdy asystent ma działać w imieniu użytkownika przez OAuth.

Nie umieszczaj klucza API dewelopera w JavaScript przeglądarki, aplikacji mobilnej ani dystrybuowanym binarnym pliku desktopowym.

## Bazowy URL i uwierzytelnianie

- Bazowy adres URL: `https://embroideryfileconverter.com/api/developer/v1`
- Uwierzytelnianie: `Authorization: Bearer efc_live_...`
- Typ zawartości zadania: `multipart/form-data`
- Ogólny domyślny limit szybkości: 60 żądań na minutę na klucz, z osobnym limitem sieciowym
- Czas życia podpisanego adresu URL pliku: 10 minut
- [Opis OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Twórz lub unieważniaj klucze API](https://embroideryfileconverter.com/developers/keys)

Klucze API są wyświetlane raz, przechowywane tylko jako hashe SHA-256, wygasać i można je natychmiast unieważnić. Dostępne uprawnienia to `formats:read`, `usage:read`, `jobs:read` i `jobs:write`.

## Szybki start: utwórz zadanie konwersji

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

API zwraca HTTP 202, ponieważ przetwarzanie jest asynchroniczne:

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

Zachowaj zarówno `job.id`, jak i `job.workflow`. Odpytywaj endpoint zadania specyficzny dla przepływu, aż status zmieni się na `completed` lub `failed`.

## Pola tworzenia zadania

### Konwersja

Użyj `workflow=conversion` dla istniejącego pliku maszyny haftującej.

- Wymagane: `workflow`, `format` oraz `file` lub `files[]`
- Maksymalny rozmiar źródła: 50 MB na plik
- Wyjściowy `format` musi być zapisywalny i różny od wykrytego formatu źródła.

### Digitalizacja

Użyj `workflow=digitising` dla grafiki JPG, JPEG, PNG, SVG lub WebP.

- Wymagane: `workflow`, `format`, `file` lub `files[]`, `width_mm` oraz `colour_count`
- `width_mm`: liczba od 10 do 300
- `colour_count`: liczba całkowita od 1 do 24
- Maksymalny rozmiar źródła: 20 MB na plik

`files[]` akceptuje do 10 źródeł w jednym wsadzie. Konta z ograniczonym darmowym przetwarzaniem mogą być ograniczone do jednego źródła na żądanie. Każdy plik w wsadzie używa tego samego workflow i formatu wyjściowego.

## Odpytaj zadanie

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

Możliwe statusy to `queued`, `processing`, `completed` i `failed`. Szczegółowa odpowiedź zadania zawiera metryki, ostrzeżenia, informacje o błędach, zdarzenia, artefakty podglądu, dane wyjściowe, stan odblokowania oraz tymczasowe podpisane adresy URL plików. Odpytaj zadanie ponownie, gdy podpisany adres URL wygaśnie.

## Pełna dokumentacja endpointów

- `GET /formats` wymaga `formats:read` i zwraca `data[]` oraz `artworkInputs[]`.
- `GET /usage` wymaga `usage:read` i zwraca `freeUsage`, w tym limit, kredyty, koszty workflow oraz daty resetu.
- `GET /jobs` wymaga `jobs:read` i zwraca `data[]` oraz `freeUsage` dla maksymalnie 50 ostatnich zadań użytkownika.
- `POST /jobs` wymaga `jobs:write` i tworzy jedno lub więcej prywatnych zadań podglądu asynchronicznego.
- `GET /jobs/conversion/{id}` wymaga `jobs:read` i zwraca jedno zadanie konwersji użytkownika.
- `GET /jobs/digitising/{id}` wymaga `jobs:read` i zwraca jedno zadanie digitalizacji użytkownika.
- `POST /jobs/conversion/{id}/retry` i `POST /jobs/digitising/{id}/retry` wymagają `jobs:write`. Ponowić można tylko nieudane zadania z niewygasłym źródłem.
- `POST /jobs/conversion/{id}/unlock` i `POST /jobs/digitising/{id}/unlock` wymagają `jobs:write`. Zadanie musi być ukończone.
- Podpisane adresy URL `GET /uploads/{id}/download` i `GET /uploads/{id}/preview` wymagają `jobs:read`; używaj pełnego adresu URL zwróconego w odpowiedzi zadania, zamiast go konstruować.

## Zachowanie odblokowania

Sprawdź `job.unlock` lub `GET /usage` przed odblokowaniem. Żądanie odblokowania może zużyć dostępny przydział subskrypcji lub kredyty przetwarzania już na koncie. Konta wewnętrzne mogą odblokować bez opłaty. Nie otwiera to kasy ani zakupu kredytów. Niewystarczający limit lub kredyty zwraca błąd walidacji.

## Błędy i zachowanie ponowień

- `401`: brakujący, niepoprawny, wygasły lub unieważniony klucz deweloperski
- `403`: brak uprawnienia klucza lub zasób należy do innego konta
- `404`: nie znaleziono zadania lub pliku prywatnego
- `409`: bieżący stan zadania nie pozwala na ponowienie ani odblokowanie
- `410`: prywatne źródło przesyłania wygasło
- `422`: niepoprawne pola, plik źródłowy, format wyjściowy lub niewystarczający limit
- `429`: przekroczono limit szybkości; honoruj `Retry-After` i stosuj wykładnicze wycofanie z jitterem

Tworzenie zadań jest chronione limitami przesyłania i przetwarzania, a trasy odblokowania mają surowszy limit działań billingowych. Unikaj agresywnego odpytywania i zatrzymaj się po statusie terminalnym.

## Model bezpieczeństwa

Pliki klientów pozostają prywatne. Każde zapytanie zadania jest ograniczone do właściciela klucza API, podpisane adresy URL wygasają, pobieralne pliki maszynowe pozostają zablokowane do czasu pozytywnego sprawdzenia uprawnień, a uprawnienia klucza są egzekwowane przed wykonaniem żądanej operacji.

## Powiązane strony

- [Agenci AI i MCP](https://embroideryfileconverter.com/pl/ai-agents)
- [Obsługiwane formaty haftu](https://embroideryfileconverter.com/pl/formats)
- [Prywatność i przechowywanie plików](https://embroideryfileconverter.com/pl/privacy)