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ý
UNAUTHORIZED401/403Request 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_TOKEN401Token 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_EXPIRED401Token đã 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_REVOKED401Token đã 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_EXCEEDED429Vượ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_TYPE400File 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_LARGE413File 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_BASE64400Trườ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_FOUND400Tà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_FAILED408/400Quá 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_ERROR500Lỗi hệ thống ngoài dự kiến.Ghi lại requestId và liên hệ support/admin.