# Embroidery File Converter Developer API

Trang chính tắc: https://embroideryfileconverter.com/vi/developers

Xây dựng quy trình thêu với REST API riêng cho số hóa ảnh, chuyển đổi tệp, trạng thái công việc, đầu ra đã xác thực và tải xuống đã ký.

## Chọn tích hợp phù hợp

- Sử dụng REST API trên trang này cho backend, sản phẩm SaaS, quy trình ecommerce, tự động hóa hoặc ứng dụng phía máy chủ.
- Sử dụng [tài liệu tác nhân AI và MCP](https://embroideryfileconverter.com/vi/ai-agents) khi trợ lý cần hành động thay mặt người dùng qua OAuth.

Không đặt khóa API nhà phát triển trong JavaScript trình duyệt, ứng dụng di động hoặc tệp nhị phân desktop phân phối.

## URL cơ sở và xác thực

- URL cơ sở: `https://embroideryfileconverter.com/api/developer/v1`
- Xác thực: `Authorization: Bearer efc_live_...`
- Loại nội dung công việc: `multipart/form-data`
- Giới hạn tốc độ mặc định chung: 60 yêu cầu mỗi phút mỗi khóa, với trần mạng riêng
- Thời hạn URL file đã ký: 10 phút
- [Mô tả OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Tạo hoặc thu hồi khóa API](https://embroideryfileconverter.com/developers/keys)

Khóa API chỉ hiển thị một lần, chỉ được lưu dưới dạng băm SHA-256, hết hạn và có thể thu hồi ngay lập tức. Các khả năng có sẵn là `formats:read`, `usage:read`, `jobs:read` và `jobs:write`.

## Bắt đầu nhanh: tạo công việc chuyển đổi

```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 trả về HTTP 202 vì xử lý bất đồng bộ:

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

Lưu trữ cả `job.id` và `job.workflow`. Thăm dò điểm cuối công việc theo quy trình cụ thể cho đến khi trạng thái trở thành `completed` hoặc `failed`.

## Trường tạo công việc

### Chuyển đổi

Sử dụng `workflow=conversion` cho file máy thêu hiện có.

- Bắt buộc: `workflow`, `format` và `file` hoặc `files[]`
- Kích thước nguồn tối đa: 50 MB mỗi file
- Định dạng đầu ra `format` phải ghi được và khác với định dạng nguồn đã phát hiện.

### Số hóa

Sử dụng `workflow=digitising` cho tác phẩm JPG, JPEG, PNG, SVG hoặc WebP.

- Bắt buộc: `workflow`, `format`, `file` hoặc `files[]`, `width_mm` và `colour_count`
- `width_mm`: số từ 10 đến 300
- `colour_count`: số nguyên từ 1 đến 24
- Kích thước nguồn tối đa: 20 MB mỗi file

`files[]` chấp nhận tối đa 10 nguồn trong một lô. Tài khoản dùng gói xử lý miễn phí hạn chế có thể bị giới hạn một nguồn mỗi yêu cầu. Mọi tệp trong lô dùng cùng quy trình và định dạng đầu ra.

## Kiểm tra công việc

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

Trạng thái có thể là `queued`, `processing`, `completed` và `failed`. Phản hồi chi tiết công việc chứa số liệu, cảnh báo, thông tin lỗi, sự kiện, bản xem trước, đầu ra, trạng thái mở khóa và URL tệp đã ký tạm thời. Gọi lại công việc khi URL đã ký hết hạn.

## Tham chiếu endpoint đầy đủ

- `GET /formats` yêu cầu `formats:read` và trả về `data[]` cùng `artworkInputs[]`.
- `GET /usage` yêu cầu `usage:read` và trả về `freeUsage`, bao gồm hạn mức, tín dụng, chi phí quy trình và ngày đặt lại.
- `GET /jobs` yêu cầu `jobs:read` và trả về `data[]` cùng `freeUsage` cho tối đa 50 công việc gần đây của chủ sở hữu.
- `POST /jobs` yêu cầu `jobs:write` và tạo một hoặc nhiều công việc xem trước không đồng bộ riêng tư.
- `GET /jobs/conversion/{id}` yêu cầu `jobs:read` và trả về một công việc chuyển đổi định dạng thuộc sở hữu.
- `GET /jobs/digitising/{id}` yêu cầu `jobs:read` và trả về một công việc số hóa thêu thuộc sở hữu.
- `POST /jobs/conversion/{id}/retry` và `POST /jobs/digitising/{id}/retry` yêu cầu `jobs:write`. Chỉ công việc thất bại có nguồn chưa hết hạn mới được thử lại.
- `POST /jobs/conversion/{id}/unlock` và `POST /jobs/digitising/{id}/unlock` yêu cầu `jobs:write`. Công việc phải đã hoàn tất.
- URL đã ký `GET /uploads/{id}/download` và `GET /uploads/{id}/preview` yêu cầu `jobs:read`; dùng URL đầy đủ được trả về trong phản hồi công việc thay vì tự tạo.

## Hành vi mở khóa

Kiểm tra `job.unlock` hoặc `GET /usage` trước khi mở khóa. Yêu cầu mở khóa có thể tiêu hao quyền đăng ký có sẵn hoặc tín dụng xử lý đã có trong tài khoản. Tài khoản nội bộ có thể mở khóa miễn phí. Thao tác này không mở trang thanh toán hoặc mua tín dụng. Hạn mức hoặc tín dụng không đủ sẽ trả về lỗi xác thực.

## Lỗi và hành vi thử lại

- `401`: thiếu, sai định dạng, hết hạn hoặc đã thu hồi khóa nhà phát triển
- `403`: thiếu khả năng của khóa hoặc tài nguyên thuộc tài khoản khác
- `404`: không tìm thấy công việc hoặc tệp riêng tư
- `409`: trạng thái công việc hiện tại không cho phép thử lại hoặc mở khóa
- `410`: tệp nguồn riêng tư đã hết hạn
- `422`: trường không hợp lệ, tệp nguồn, định dạng đầu ra hoặc hạn mức không đủ
- `429`: đã vượt giới hạn tốc độ; tuân thủ `Retry-After` và dùng exponential backoff với jitter

Tạo công việc cũng được bảo vệ bởi giới hạn tải lên và xử lý, còn tuyến mở khóa có giới hạn hành động thanh toán chặt hơn. Tránh polling liên tục và dừng sau trạng thái kết thúc.

## Mô hình bảo mật

Tệp khách hàng giữ riêng tư. Mọi truy vấn công việc chỉ dành cho chủ sở hữu API key, URL đã ký hết hạn, tệp máy có thể tải vẫn khóa cho đến khi kiểm tra quyền thành công, và khả năng của khóa được thực thi trước khi chạy thao tác yêu cầu.

## Trang liên quan

- [AI agents và MCP](https://embroideryfileconverter.com/vi/ai-agents)
- [Định dạng thêu được hỗ trợ](https://embroideryfileconverter.com/vi/formats)
- [Quyền riêng tư và giữ tệp](https://embroideryfileconverter.com/vi/privacy)