Cách gửi PDF lên API dưới dạng Base64
API hóa đơn điện tử, chữ ký điện tử hay vận chuyển muốn nhận tài liệu trong một trường JSON. Đây là cách biến PDF thành đúng loại văn bản cần thiết, kiểm tra nó và tránh những lỗi khiến yêu cầu thất bại.
Tác giả: Metin Ersoy · Cập nhật 10 tháng 11, 2026
API thường cần gì
Phần lớn API xử lý tài liệu mô tả một phần thân JSON có trường tên là content, file, data hoặc document. Giá trị của trường này là mã Base64 của PDF, thường đi kèm tên tệp và loại tệp:
{
"fileName": "invoice-1024.pdf",
"mimeType": "application/pdf",
"content": "JVBERi0xLjcKJ..."
}
Trước khi viết dòng code nào, hãy đọc tài liệu API để nắm ba điều: tên trường, có cần tiền tố data: hay không (thường là không) và giới hạn dung lượng.
1. Chuyển PDF sang Base64
Cách nhanh nhất để có một giá trị thử nghiệm là dùng PDF sang Base64. Chọn tệp PDF, chọn Chỉ mã Base64 (bắt đầu bằng JVBERi0) rồi sao chép kết quả. Nếu muốn có sẵn cả phần thân yêu cầu để bắt đầu, hãy chọn JSON gồm tên tệp, loại và nội dung: tùy chọn này tự thêm tên tệp và loại tệp cho bạn. PDF được mã hóa ngay trong trình duyệt và không bị tải lên, điều này rất quan trọng khi tài liệu thử nghiệm là một hóa đơn thật.
Hãy kiểm tra kết quả: chuỗi phải bắt đầu bằng JVBERi0, không có khoảng trắng và, ngoài một hoặc hai dấu = ở cuối, chỉ gồm chữ cái, chữ số, dấu + và /.
2. Gửi đi từ code của bạn
Cùng một bước trong ba ngôn ngữ phổ biến. Mỗi đoạn đều đọc tệp, mã hóa rồi gửi JSON:
# curl (Linux / macOS): base64 -w 0 keeps it on one line
curl -X POST https://api.example.com/documents \
-H "Content-Type: application/json" \
-d "{\"fileName\":\"invoice.pdf\",\"content\":\"$(base64 -w 0 invoice.pdf)\"}"
// Node.js 18+
import { readFile } from 'node:fs/promises';
const content = (await readFile('invoice.pdf')).toString('base64');
await fetch('https://api.example.com/documents', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fileName: 'invoice.pdf', content }),
});
# Python 3 with requests
import base64, requests
with open("invoice.pdf", "rb") as f:
content = base64.b64encode(f.read()).decode("ascii")
requests.post("https://api.example.com/documents",
json={"fileName": "invoice.pdf", "content": content})
Trên macOS, dòng curl dùng base64 -i invoice.pdf thay cho -w 0. Địa chỉ và tên trường ở đây chỉ là ví dụ; hãy dùng đúng những gì tài liệu của dịch vụ bạn quy định.
3. Kiểm tra cả chiều đi lẫn chiều về
Nếu dịch vụ trả về tài liệu hoặc một bản lưu dưới dạng Base64, hãy dán phản hồi đó vào Base64 sang PDF. Nhìn thấy trang đầu tiên và số trang là cách nhanh nhất để chắc chắn không có gì bị mất dọc đường. Các bước chi tiết cho chiều này có trong Cách lưu chuỗi Base64 thành tệp PDF.
Lỗi thường gặp
| Dấu hiệu | Nguyên nhân có thể | Cách khắc phục |
|---|---|---|
| "Invalid Base64" (Base64 không hợp lệ) | Có dấu xuống dòng (dòng 76 ký tự) hoặc tiền tố data: | Gửi mã thuần trên một dòng |
| "Payload too large" (413, dữ liệu quá lớn) | PDF quá nặng sau khi mã hóa | Giảm dung lượng bằng Nén PDF |
| PDF mở ra trắng trơn hoặc bị hỏng | Chuỗi bị cắt mất một đoạn | Mã hóa lại và gửi đủ toàn bộ giá trị |
| Tên có dấu hiển thị sai | Tên tệp được gửi sai bảng mã | Giữ phần thân JSON ở UTF-8 |
Sẵn sàng thử chưa? Hoàn toàn miễn phí và tệp của bạn vẫn ở trên thiết bị.
Mở công cụ PDF sang Base64