8.2. Lỗi Chuyển đổi Khống Format (File Conversion Issues)

Một trong những vấn đề đau đầu nhất là khi người dùng Upload một file không chính thống nhưng "vô tình hoặc cố ý" bị đổi sai định dạng đuôi file.

Hiện tượng: Quăng lỗi UnsupportedFileFormatException khi đang thực thi bộ chuyển đổi Aspose.Words (ví dụ: Chuyển .docx sang .pdf). Nguyên nhân gốc rễ (Root Cause): File thực chất đã là chuẩn .pdf bên trong, nhưng người dùng (hoặc hệ thống tạo tự động) lại đang lưu tên nó với đuôi mở rộng là .docx. Bộ máy Aspose Words tiếp nhận file tưởng đây là Word, mở ra thấy sai logic binaire của Office thì quăng lỗi. Cách xử lý & Cách dự án giải quyết: Vấn đề này đã được Patch trong nhánh xử lý của SigningController. Hệ thống sử dụng cơ chế đọc Magic Bytes để xem cấu trúc thật của Core File (Hex Header bắt đầu bằng %PDF- thì by-pass cơ chế converter của Word/Excel và coi thẳng đó là PDF). Đảm bảo File luôn lọt qua máy chủ ký tự động.

8.3. Lỗi Request OTP & Authentication (HTTP 400/401)

Dự án áp dụng logic ký bảo mật qua Session OTP sinh tự động. Lỗi thường phát sinh tại API /api/sign/request-otp và API ký.

Hiện tượng: Web/Portal trả về thông điệp lỗi HTTP status 400 Bad Request, hoặc "Phiên ký không hợp lệ". Cách khắc phục:

Khi gọi /api/sign, Client bắt buộc phải có thông tin Token phiên làm việc ở Header Token-Signing.
Dữ liệu Request OTP yêu cầu người dùng (username) và email được cấp từ SecurityUtils phải đúng cấu trúc. IT cần kiểm tra hệ thống tài khoản E-Office đã gửi User Context hợp lệ sang khối Ký số chưa (Nếu Header OAuth/JWT truyền qua sai username, Service sẽ ngắt lệnh).