Developer API
Tài liệu API Verify PDF/XML
Tích hợp API kiểm tra chữ ký số bằng Bearer token nội bộ, không dùng Google token trực tiếp.
Endpoint upload file
curl -X POST "https://ca.9two.net/api/v1/verify/file" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "[email protected]"
Endpoint base64
curl -X POST "https://ca.9two.net/api/v1/verify/base64" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "fileName": "contract.pdf", "contentType": "application/pdf", "base64Content": "JVBERi0xLjQK..." }'
Ví dụ C# HttpClient
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
using var form = new MultipartFormDataContent();
form.Add(new StreamContent(File.OpenRead("contract.pdf")), "file", "contract.pdf");
var response = await client.PostAsync("https://ca.9two.net/api/v1/verify/file", form);
Response tổng quan
Response thành công trả danh sách chữ ký số và documentSummary để client biết ngay tài liệu còn nguyên vẹn, đã bị chỉnh sửa hoặc có chữ ký chưa tin cậy.
{
"success": true,
"requestId": "00-...",
"fileName": "contract.pdf",
"fileType": "PDF",
"signatureCount": 2,
"documentSummary": {
"label": "Thông tin tài liệu",
"title": "Tài liệu còn nguyên vẹn và chưa bị chỉnh sửa",
"message": "Có ít nhất 1 chữ ký số có nguồn Chưa tin cậy (hoặc có thể là self cert)",
"status": "IntactWithUntrustedSignature",
"isDocumentIntact": true,
"hasUntrustedSignature": true,
"isUsable": false
},
"results": []
}
Mã lỗi chuẩn hóa
| Mã lỗi | HTTP status | Ý nghĩa | Hướng xử lý |
|---|---|---|---|
UNAUTHORIZED | 401/403 | Request không có quyền truy cập API hoặc user bị khóa. | Kiểm tra Bearer token và trạng thái tài khoản. |
INVALID_TOKEN | 401 | Token sai format, sai hash hoặc không tồn tại. | Tạo token mới trong trang API Tokens và gửi đúng header Authorization. |
TOKEN_EXPIRED | 401 | Token đã vượt quá ngày hết hạn. | Rotate hoặc tạo token mới, sau đó cập nhật client application. |
TOKEN_REVOKED | 401 | Token đã bị user hoặc admin thu hồi. | Dừng dùng token cũ và tạo token mới nếu còn nhu cầu. |
QUOTA_EXCEEDED | 429 | Vượt giới hạn request theo ngày hoặc tháng. | Chờ quota reset hoặc nâng hạn mức khi có paid plan. |
INVALID_FILE_TYPE | 400 | File không phải PDF/XML hợp lệ, MIME sai hoặc magic header không khớp. | Gửi file PDF/XML thật, content-type đúng và không đổi đuôi giả. |
FILE_TOO_LARGE | 413 | File vượt giới hạn upload cấu hình. | Giảm dung lượng file hoặc liên hệ để nâng giới hạn. |
INVALID_BASE64 | 400 | Trường base64Content không decode được. | Encode lại nội dung file bằng Base64 chuẩn, không thêm prefix data URI. |
NO_SIGNATURE_FOUND | 400 | Tài liệu hợp lệ nhưng không có chữ ký số hỗ trợ. | Kiểm tra lại file nguồn hoặc quy trình ký số. |
VERIFICATION_FAILED | 408/400 | Quá trình verify không hoàn tất, timeout hoặc dữ liệu chữ ký lỗi. | Thử lại với file khác hoặc kiểm tra tình trạng CA/CRL/OCSP. |
INTERNAL_ERROR | 500 | Lỗi hệ thống ngoài dự kiến. | Ghi lại requestId và liên hệ support/admin. |