Hướng dẫn cho lập trình viên

Paginta

Một sản phẩm của Belumind · PDF sang Word · EN / VI / FR

Biến báo cáo dài, trang nhiều cột và báo cáo tài chính thành tệp Word mà mọi bảng đều là bảng thật, bấm vào là sửa được. Tốt nhất với tiếng Anh, tiếng Việt và tiếng Pháp, giữ nguyên dấu. Không bao giờ viết lại hay tóm tắt — trên trang có gì thì tài liệu có nấy — và mỗi lần chuyển đổi đều kèm báo cáo kiểm tra: bao nhiêu trang và bảng, chữ lỗi nào đã được sửa, và bao nhiêu ô bảng khớp với bản gốc.

Địa chỉ cho phần mềm của bạn (API)

https://api.belumind.com/paginta

Địa chỉ cho trợ lý AI (MCP)

https://mcp.belumind.com/paginta/mcp

Ô bảng khớp: 1.753 / 1.753
Bảng giữ nguyên cấu trúc: 44 / 45
Trang thường: ~1–5 giây / trang
Trang scan: ~5 giây / trang

Key truy cập

Mọi yêu cầu đều gửi kèm hai thứ: API key cho sản phẩm này, tạo trong trang quản lý ở mục API key, và access token của người dùng đang đăng nhập sở hữu key đó. Token có hạn 15 phút, nên hãy làm mới và gửi token mới. Key tạo cho sản phẩm khác sẽ nhận lỗi 403 — nhờ vậy, bạn có thể giao cho trợ lý AI một key chỉ dùng được đúng một công cụ và không gì khác.

Trợ lý AI gửi cùng hai header đó khi kết nối tới địa chỉ ở trên.

documents:convert

Cách gửi key

X-API-Key: bm_live_7f3c…
Authorization: Bearer eyJhbGciOi…
Content-Type: application/json

POST/v1/documentsdocuments:convert

Gửi PDF để chuyển đổi

Kiểm tra tệp ngay — dung lượng, số trang, gói và hạn mức tháng — nên nếu có vấn đề (lỗi 413, 402 hay 429) bạn sẽ biết ngay thay vì sau khi chuyển đổi. Sau đó việc chuyển đổi được bắt đầu và bạn nhận mã ngay lập tức. Xem kết quả bằng `GET /v1/documents/{doc_id}`. Nếu muốn nhận tệp Word trong một bước, `POST /convert` nhận cùng tệp và trả về chính tệp .docx; header `X-Font-Garbled` và `X-Repaired-Cells` cho biết chất lượng. Qua MCP, tệp trên máy người dùng được tải lên `https://mcp.belumind.com/paginta/uploads` trước, rồi `upload_id` nhận được truyền cho `convert_pdf`; công cụ `service_status` cho biết dịch vụ có hoạt động không và đang bận đến đâu.

Công cụ cho trợ lý AIconvert_pdf

Nội dung cần gửi

filefilebắt buộc: Tệp PDF. Tệp rỗng hoặc hỏng trả lỗi 400; PDF scan cần nhận dạng chữ, chỉ có ở gói Pro (402); tệp vượt dung lượng hoặc số trang của gói trả lỗi 413.

Kết quả nhận về

202 AcceptedĐã nhận — đang chờ đến lượt xử lý.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X POST https://api.belumind.com/paginta/v1/documents \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN" \
  -F "file=@annual-report-2024.pdf"

Bạn nhận về

application/json202 Accepted

{
  "job_id": "6s_4aek7-1792405943",
  "status": "queued"
}

Thử ngay

Chế độ ví dụ

API keyAccess tokenNội dung cần gửi

POST https://api.belumind.com/paginta/v1/documents

Nền tảng đang trong giai đoạn truy cập sớm, nên ô này hiển thị câu trả lời mẫu thay vì liên hệ dịch vụ thật. Hãy xin chúng tôi một key và chính ô này sẽ gửi yêu cầu thật.

GET/v1/documents/{doc_id}documents:convert

Xem kết quả và báo cáo kiểm tra

Cho biết việc chuyển đổi đã xong chưa và, khi xong, báo cáo kiểm tra: số trang, số bảng, thời gian xử lý, số trang scan, chữ đã sửa và — khi có đối chiếu bản gốc — bao nhiêu ô bảng khớp hoàn toàn, bao nhiêu ô bị mất (phải bằng 0) và bao nhiêu bảng giữ nguyên cấu trúc. Khi `downloadable` là true, `GET /v1/documents/{doc_id}/download` trả về đường link tải tệp .docx, dùng được trong thời gian ngắn.

Công cụ cho trợ lý AIget_document

Tuỳ chọn trong địa chỉ

doc_idstring · pathbắt buộc: Mã bạn nhận được khi gửi PDF, hoặc lấy từ danh sách (`GET /v1/documents`).

Kết quả nhận về

200 OKThành công. Bạn nhận về đúng như ví dụ.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X GET https://api.belumind.com/paginta/v1/documents/{doc_id} \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN"

Bạn nhận về

application/json200 OK

{
  "job_id": "6s_4aek7-1792405943",
  "status": "done",
  "name": "annual-report-2024.pdf",
  "pages": 93,
  "tables": 45,
  "bytes": 4182337,
  "ms": 88400,
  "error": null,
  "error_code": null,
  "downloadable": true,
  "verification": {
    "font_garbled": false,
    "repaired_cells": 12,
    "scanned": false,
    "cells_src": 1753,
    "cell_exact": 1753,
    "cell_lost": 0,
    "shape_ok": 44,
    "shape_total": 45,
    "text_recall": 1,
    "level": "per_cell",
    "detail": null
  }
}

Thử ngay

Chế độ ví dụ

API keyAccess token

doc_id

GET https://api.belumind.com/paginta/v1/documents/

GET/v1/documentsdocuments:convert

Lịch sử chuyển đổi và giới hạn gói

Các lần chuyển đổi của bạn, mới nhất trước, mỗi mục cùng thông tin như khi xem một tài liệu — kèm gói và giới hạn của gói: số trang mỗi tệp, số tài liệu mỗi tháng, dung lượng tải lên tối đa, và có hỗ trợ trang scan không. `limit` quy định số mục hiển thị; mặc định là 200.

Công cụ cho trợ lý AIlist_documents

Tuỳ chọn trong địa chỉ

limitinteger · querytuỳ chọn: Số lần chuyển đổi hiển thị. Mặc định là 200.

Kết quả nhận về

200 OKThành công. Bạn nhận về đúng như ví dụ.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X GET https://api.belumind.com/paginta/v1/documents \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN"

Bạn nhận về

application/json200 OK

{
  "documents": [
    {
      "doc_id": "6s_4aek7-1792405943",
      "name": "annual-report-2024.pdf",
      "status": "done",
      "pages": 93,
      "tables": 45,
      "downloadable": true
    }
  ],
  "count": 1,
  "plan": "pro",
  "limits": {
    "pages_per_file": 20,
    "documents_per_month": 1000000,
    "max_upload_mb": 25,
    "ocr": true
  }
}

Thử ngay

Chế độ ví dụ

API keyAccess token

GET https://api.belumind.com/paginta/v1/documents

Dùng với trợ lý AI

Khi kết nối với trợ lý AI, Paginta có thể nhận tệp PDF người dùng gửi vào khung chat và trả lại một tệp Word sửa được — rồi dựa vào báo cáo kiểm tra để cho biết bảng nào, nếu có, cần xem lại trước khi gửi tài liệu đi. Paginta không mở được tệp trên máy người dùng, nên tệp được tải lên trước; tệp PDF đã có trên mạng thì gửi bằng đường link.

Bạn hỏi

“Chuyển báo cáo kiểm toán ngân hàng này sang Word để tôi sửa các bảng.”

Trợ lý sẽ

01Tải tệp lên, rồi nhờ Paginta chuyển đổi
02Gửi người dùng đường link tải tệp Word, dùng được trong thời gian ngắn
03Đọc báo cáo kiểm tra và chỉ ra bảng nào chưa giữ nguyên cấu trúc

Cài đặt để dán vào trợ lý AI

{
  "mcpServers": {
    "paginta": {
      "url": "https://mcp.belumind.com/paginta/mcp",
      "headers": {
        "X-API-Key": "bm_live_7f3c…",
        "Authorization": "Bearer eyJhbGciOi…"
      }
    }
  }
}

Khi có sự cố

Khi một yêu cầu thất bại, bạn nhận được một số lỗi tiêu chuẩn và một code ngắn để phần mềm của bạn xử lý, kèm một thông báo dễ hiểu cho người đọc. Mỗi yêu cầu có thể kèm Idempotency-Key, nên gửi lại sau sự cố phía chúng tôi là an toàn — việc sẽ không bị làm hai lần.

Lỗi trông như thế nào4xx / 5xx

{
  "error": {
    "code": "invalid_parameter",
    "message": "`url` must be a reachable http(s) URL.",
    "param": "url",
    "request_id": "req_4d91c0b7"
  }
}

Sẵn sàng dùng thật?

Trong giai đoạn truy cập sớm, ô "Thử ngay" hiển thị câu trả lời mẫu. Hãy cho chúng tôi biết bạn đang xây gì, chúng tôi sẽ cấp key cho bạn.