Tham khảo Connect REST API

Tổng quan nhanh

NextPDF Connect cung cấp sổ đăng ký công cụ qua HTTP dưới dạng một transport REST, được mô tả bằng hợp đồng OpenAPI 3.1. Trang này là tài liệu tham khảo cho bề mặt đó: base URL, cách xác thực, các nhóm thao tác, và mô hình lỗi. Đặc tả đầy đủ ở dạng máy đọc được được công bố để bạn có thể nạp vào một trình khám phá tương tác, một bộ tạo client, hoặc một request client mà không cần sao chép thủ công.

Để xem danh mục công cụ độc lập với transport (cùng các thao tác qua Model Context Protocol, gRPC, và REST), hãy xem tài liệu tham khảo Connect API. Để xem pipeline RoadRunner, cách triển khai, và thiết lập xác thực, hãy xem hướng dẫn transport REST.

Base URL và xác thực

Transport REST lắng nghe trên host và cổng được cấu hình cho bản triển khai của bạn. Khi chạy cục bộ, địa chỉ là http://localhost:8080; trong môi trường production, đó là địa chỉ đứng trước nhóm worker của bạn.

Xác thực dùng bearer token. Gửi API key trong header Authorization cho mọi yêu cầu đến route bị giới hạn theo bậc:

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

Các probe liveness và readiness chỉ đọc không yêu cầu token.

Thao tác

Tính khả dụng được giới hạn theo bậc. Phần lõi mã nguồn mở cung cấp các thao tác document, render, session, và job. Việc ký, điền biểu mẫu, bôi đen, so sánh, kiểm tra khả năng truy cập, và tối ưu hóa cần một phiên bản thương mại được cài đặt cùng máy chủ. Endpoint capabilities trả về tập hợp chính thức cho từng bản triển khai cụ thể. Hãy truy vấn endpoint này thay vì giả định một danh sách cố định.

Tình trạng và vòng đời

Phương thức	Đường dẫn	Mục đích
GET	/healthz	Probe liveness. Không xác thực.
GET	/readyz	Probe readiness (các phụ thuộc và nhóm worker đã sẵn sàng). Không xác thực.
GET	/api/v1/capabilities	Các công cụ và bậc mà bản triển khai này thực sự cung cấp. Hãy truy vấn endpoint này trước.

Kết xuất và tài liệu

Phương thức	Đường dẫn	Mục đích
POST	/api/v1/render	Kết xuất tài liệu từ một danh sách thao tác có thứ tự và trả về PDF.
POST	/api/v1/extract-text	Trích xuất nội dung văn bản từ một PDF.
POST	/api/v1/merge	Gộp nhiều đầu vào PDF thành một tài liệu duy nhất.
POST	/api/v1/split	Tách một PDF thành nhiều tài liệu.

Tác vụ bất đồng bộ

Phương thức	Đường dẫn	Mục đích
POST	/api/v1/jobs	Gửi một thao tác chạy lâu dưới dạng một tác vụ.
GET	/api/v1/jobs/{id}	Thăm dò trạng thái tác vụ.
GET	/api/v1/jobs/{id}/result	Lấy kết quả tác vụ đã hoàn tất.

Phiên

Phiên giữ một tài liệu mở qua nhiều lệnh gọi để bạn dựng từng phần và kết xuất một lần ở cuối.

Phương thức	Đường dẫn	Mục đích
POST	/api/v1/sessions	Mở một phiên.
GET / DELETE	/api/v1/sessions/{sessionId}	Kiểm tra hoặc đóng một phiên.
POST	/api/v1/sessions/{sessionId}/pages	Thêm một trang.
POST	/api/v1/sessions/{sessionId}/text	Thêm văn bản.
POST	/api/v1/sessions/{sessionId}/images	Thêm hình ảnh.
POST	/api/v1/sessions/{sessionId}/tables	Thêm một bảng.
POST	/api/v1/sessions/{sessionId}/html	Thêm HTML đã kết xuất.
POST	/api/v1/sessions/{sessionId}/font	Đặt phông chữ đang hoạt động.
POST	/api/v1/sessions/{sessionId}/render	Kết xuất tài liệu của phiên.

Thao tác của phiên bản thương mại

Các route này chỉ được đăng ký khi phiên bản thương mại tương ứng đã được cài đặt. Một số route bị giới hạn và cần phê duyệt qua luồng xác nhận có con người trong vòng lặp; hãy xem các bậc rủi ro.

Phương thức	Đường dẫn	Mục đích
POST	/api/v1/sign	Áp dụng một chữ ký số.
POST	/api/v1/fill-form	Điền một biểu mẫu tương tác.
POST	/api/v1/redact	Bôi đen nội dung.
POST	/api/v1/compare	So sánh hai tài liệu PDF.
POST	/api/v1/check-accessibility	Chạy bài kiểm tra khả năng truy cập về cấu trúc.
POST	/api/v1/optimize	Tối ưu hóa và thu gọn tài liệu.

Mô hình lỗi

Transport REST dùng các mã trạng thái HTTP với ngữ nghĩa được RFC 9110 định nghĩa: 2xx cho thành công, 4xx cho yêu cầu mà phía gọi phải sửa (400 phần thân không hợp lệ, 401 token thiếu hoặc không hợp lệ, 403 bị từ chối theo bậc hoặc phê duyệt, 404 route hoặc tác vụ không xác định, 409 xung đột idempotency, 422 yêu cầu đúng định dạng nhưng engine không thể xử lý), và 5xx cho lỗi phía máy chủ. Phản hồi 401 mang theo challenge WWW-Authenticate.

Phần thân lỗi là tài liệu application/problem+json theo RFC 9457 (Problem Details for HTTP APIs): một type ổn định, một title ngắn, status dạng số, và một detail mà con người đọc được. Hãy khớp theo type, không khớp theo chuỗi detail. Xem thêm RFC 9110 (HTTP Semantics) và RFC 9457 để biết các định nghĩa quy chuẩn.

Hãy gửi các yêu cầu làm thay đổi trạng thái kèm header Idempotency-Key để yêu cầu được thử lại chỉ được xử lý một lần.

Đặc tả ở dạng máy đọc được

Hợp đồng đầy đủ được công bố dưới dạng tài liệu OpenAPI 3.1 tĩnh:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

Hãy dùng tài liệu này làm nguồn chân lý duy nhất cho bề mặt REST:

1. Mở trình khám phá API tương tác — một tài liệu tham khảo Scalar trong trình duyệt, tự host, được tạo từ hợp đồng này — để đọc và thử mọi thao tác cùng schema yêu cầu và phản hồi tương ứng.
2. Nhập nó vào một request client như Postman hoặc Insomnia.
3. Tạo một client có kiểu cho ngôn ngữ của bạn bằng một bộ tạo OpenAPI.

Tài liệu này là hợp đồng tĩnh, được ghim phiên bản theo gói. Nó không được phục vụ bởi endpoint trực tiếp, nên vẫn ổn định qua các bản triển khai.

Xem thêm

• Tài liệu tham khảo Connect API — danh mục công cụ đầy đủ trên MCP, REST, và gRPC.
• Hướng dẫn transport REST — pipeline RoadRunner, xác thực bearer, và định tuyến theo bậc.
• Tổng quan NextPDF Connect — máy chủ là gì và cách chạy nó.