Tài liệu API | ConvertFile

API của ConvertFile cho phép phần mềm của bạn gửi file và nhận kết quả chuyển đổi — nhận dạng tài liệu sang Word, Excel, gỡ băng âm thanh và các công cụ khác. API bất đồng bộ: tạo job → hỏi trạng thái định kỳ → tải file kết quả.

Base URL: https://convertfile.vn/api/v1/external
Xác thực: header X-API-Key trên mọi request.
Gửi file bằng multipart/form-data, nhận JSON.

1. Lấy khoá API

Đăng nhập rồi tạo khoá tại Tài khoản → Khoá API. Khoá chỉ hiển thị một lần; mất khoá thì xoay khoá mới (khoá cũ ngừng hoạt động ngay). Chỉ gọi API từ máy chủ của bạn — đừng nhúng khoá vào frontend hay ứng dụng di động.

2. Endpoint

Phương thức	Đường dẫn	Mục đích
GET	`/converters`	Danh sách công cụ đang mở, đuôi file nhận và tuỳ chọn
POST	`/jobs`	Tải lên một file, tạo job (có giới hạn số job mỗi phút)
GET	`/jobs/{id}`	Trạng thái một job
GET	`/jobs`	Danh sách job của khoá, mới nhất trước
GET	`/jobs/{id}/files/{name}`	Tải một file kết quả
GET	`/usage`	Lượng đã dùng trong tháng và hạn mức

Tạo job — POST /jobs

file (bắt buộc): một file, đuôi thuộc input_exts của công cụ.
converter_key (bắt buộc): khoá công cụ, ví dụ pdf-to-docx, pdf-to-xlsx, audio-to-text.
options (tuỳ chọn): JSON object, ví dụ {"profile":"technical"} hoặc {"diarize":true}.

Trả về 201 kèm id của job — lưu lại ngay để quay lại job nếu tiến trình của bạn bị ngắt. Thời điểm trong JSON là UTC.

Trạng thái job

`status`	Ý nghĩa
`pending`	Đã nhận, đang kiểm tra file
`queued`	Đang xếp hàng xử lý
`processing`	Đang chuyển đổi
`completed`	Xong — `results` có danh sách file kèm `download_url`
`failed`	Thất bại — xem `error_message`
`expired`	File đã bị xoá theo thời hạn lưu trữ

Hỏi trạng thái mỗi khoảng 5 giây. Tài liệu vài chục trang có thể mất 20–40 phút khi đông; dừng chờ không huỷ job — lần sau chỉ cần gọi lại GET /jobs/{id}, đừng tải file lên lại.

3. Ví dụ với curl

# Tạo job
curl -X POST "https://convertfile.vn/api/v1/external/jobs" \
  -H "X-API-Key: <API_KEY>" \
  -F "file=@bang-gia.pdf" -F "converter_key=pdf-to-xlsx"

# Hỏi trạng thái
curl "https://convertfile.vn/api/v1/external/jobs/<JOB_ID>" -H "X-API-Key: <API_KEY>"

# Tải file kết quả
curl -OJ "https://convertfile.vn/api/v1/external/jobs/<JOB_ID>/files/bang-gia.xlsx" -H "X-API-Key: <API_KEY>"

4. Tính phí

Mỗi job trừ credit trong ví của tài khoản chủ khoá theo đúng bảng giá công bố. Credit được giữ khi đo xong file và chỉ trừ thật khi job completed; job lỗi hoặc hết hạn được hoàn lại toàn bộ. Ví không đủ mức thu tối thiểu thì tạo job trả về 402.

5. Mã lỗi thường gặp

400 — công cụ không tồn tại, đuôi file sai, options không phải JSON object.
401 — thiếu khoá, sai khoá hoặc khoá đã bị thu hồi.
402 — không đủ credit; kiểm bằng trường code = "insufficient_credit".
404 — job không tồn tại hoặc thuộc khoá khác.
413 — file vượt dung lượng cho phép.
429 — vượt giới hạn tạo job mỗi phút (chờ 60 giây) hoặc hết hạn mức tháng.