API và webhook
Việc tải lên và đọc tài liệu có sẵn thông qua REST API. Quản lý tài khoản, thư mục, nhãn và kết nối vẫn ở trong ứng dụng.
Khóa
Khóa được tạo tại Cài đặt → Dành cho nhà phát triển. Khóa chỉ hiện một lần khi tạo — sau đó sẽ không hiện nữa, vì chỉ lưu lại dấu vân tay của nó. Khóa bị mất không thể phục hồi, cần tạo một khóa mới và xóa khóa cũ. Có thể có năm khóa, mỗi khóa có thời gian hiệu lực tùy chọn lên đến hai năm.
Chủ tài khoản sẽ nhận được email về mỗi khóa mới, cũng như hai tuần trước khi khóa hết hạn. Xem Thông báo qua email.
Khóa được gửi trong tiêu đề X-API-Key.
Tính năng của API
| Hoạt động | Mô tả |
|---|---|
POST /api/upload | Tải lên tệp với các tùy chọn: định dạng, hướng, loại, tiền tệ, sơ đồ, thư mục, webhook |
POST /api/upload/url | Tương tự từ địa chỉ công khai; chúng tôi sẽ tự tải tệp xuống |
GET /api/jobs | Liệt kê tài liệu với bộ lọc và phân trang |
GET /api/jobs/{id} | Trạng thái, dữ liệu đã đọc, phát hiện và kết quả trong định dạng đích |
GET /api/jobs/{id}/original | Tệp đã tải lên |
DELETE /api/jobs/{id} | Xóa vào thùng rác |
Excel và PDF được trả về dưới dạng Base64. Ai không cần kết quả thì gửi includeResult=false, sẽ tiết kiệm được việc chuyển đổi trên máy chủ.
Mô tả giao diện theo định dạng OpenAPI có ở địa chỉ /api/docs; liên kết nằm trong cài đặt của các khóa. Mô tả được tạo ra từ mã đang chạy, nên nó chính xác với những gì API thực hiện.
Kiểm tra tài liệu từ API
Kiểm tra trước khi gửi cũng áp dụng mặc định cho tài liệu được tải lên bằng khóa: tài liệu chờ xác nhận trong ứng dụng và webhook sẽ được gửi đi sau đó. Ai xây dựng tích hợp mà không ai ngồi trước màn hình có thể vào Cài đặt → Kiểm tra trước khi gửi để loại bỏ kênh API, hoặc tắt kiểm tra.
MCP
Đối với các đại lý AI, có địa chỉ /api/mcp cho máy chủ MCP với cùng khóa. Nó có thể đọc và tìm kiếm tài liệu nhưng không thể tải lên; việc tải lên sẽ trả về một lệnh hoàn tất, mà đại lý tự thực hiện.
Webhook
Thay vì truy vấn tình trạng, hãy để nhận kết quả khi hoàn thành. Địa chỉ được thiết lập cho toàn bộ tài khoản trong Cài đặt → Dành cho nhà phát triển, hoặc tại từng lần tải lên bằng tham số targetWebhookUrl. Nút trong cài đặt sẽ gửi một thông điệp thử nghiệm.
Một POST với JSON sẽ được gửi: định danh tài liệu, tên tệp, định dạng và kết quả trong định dạng đích. Khi tài liệu vượt qua kiểm tra hoặc được xử lý lại, webhook sẽ đến lần thứ hai với cờ sửa đổi (IsCorrection).
Thông điệp không được ký. Xác minh người gửi bằng cách thêm mã bí mật của riêng bạn vào địa chỉ. Các địa chỉ trong mạng riêng sẽ bị từ chối.
Khi webhook không đến sau tất cả các lần thử, khoảng bốn rưỡi giờ sau, một email sẽ được gửi. Trong một sự cố chỉ một lần, các lần thất bại khác sẽ được ghi lại trong hoạt động. Email cũng sẽ được gửi sau mỗi lần thay đổi địa chỉ webhook, nếu ai đó thay đổi không phải bạn.
Việc giao hàng không thành công sẽ được lặp lại với độ trễ gia tăng, mười một lần thử trong khoảng bốn rưỡi giờ. Mỗi lần thử sẽ có trong hoạt động kèm theo phản hồi từ phía bạn; trong tài liệu trong danh sách sẽ có biểu tượng với kết quả giao hàng.
Giới hạn
API không có giới hạn riêng về số lần gọi mỗi phút; việc tải lên bị giới hạn bởi tín dụng, kích thước tệp theo gói và hai mươi trang cho mỗi tài liệu. Việc từ chối sẽ đến dưới dạng lỗi 400 với mã cho biết lý do tại sao. Máy chủ MCP bị giới hạn ở mười truy vấn mỗi giây.