📂 Quản lý chứng từ

TKHQ đọc Invoice, Packing List, B/L, CO và các chứng từ thương mại — trích xuất dữ liệu tự động rồi áp dụng vào tờ khai hoặc lô hàng chỉ với vài click.

Upload, trích xuất và áp dụng dữ liệu từ chứng từ thương mại vào tờ khai và lô hàng. Route: /documents.

⬆️ Upload

TKHQ nhận chứng từ của bạn, tự nhận diện loại và trích xuất dữ liệu trong nền — không cần chọn template hay cấu hình trước.

Upload chứng từ để AI trích xuất dữ liệu tự động — hỗ trợ PDF và ảnh.

Định dạng hỗ trợ: PDF, JPEG, PNG, TIFF, WEBP (tối đa 50MB/file)

Loại chứng từ nhận diện tự động:

• Commercial Invoice (Invoice thương mại)
• Packing List
• Bill of Lading (B/L) / Airway Bill (AWB)
• Certificate of Origin (CO) — Form D, Form E, Form AK, EUR.1...
• Phytosanitary Certificate / Fumigation Certificate
• EIR (Equipment Interchange Receipt)
• Chứng từ tổng quát (PDF khác)

Cách upload:

1. Vào /documents → nút + Upload chứng từ
2. Kéo thả file hoặc click chọn file từ máy tính
3. Hệ thống tự nhận diện loại chứng từ
4. AI bắt đầu trích xuất trong nền (30–120 giây tuỳ độ phức tạp)
5. Nhận thông báo khi trích xuất xong

Loại chứng từ điền sẵn khi upload một file

Nếu bạn thả đúng một file, loại chứng từ hệ thống nhận diện được sẽ điền sẵn để bạn xác nhận nhanh. Khi thả nhiều file cùng lúc, mỗi file được nhận diện riêng nên ô loại chứng từ không điền sẵn.

Upload thẳng vào một lô hàng

Khi mở upload từ trong một lô hàng, chứng từ được gắn luôn vào lô hàng đó ngay trong lần upload — không cần thao tác đính kèm lần hai.

Upload hàng loạt

Chọn nhiều file cùng lúc (Ctrl+Click hoặc Shift+Click) — hệ thống xử lý song song, không cần chờ từng file.

🔍

Drag & drop nhiều file — AI nhận diện loại và trích xuất song song

📋 Danh sách

Quản lý toàn bộ chứng từ trong workspace.

Bộ lọc và tìm kiếm:

Bộ lọc	Giá trị
Loại chứng từ	Invoice, Packing List, B/L, CO, EIR, Khác
Trạng thái	Đang xử lý, Đã trích xuất, Lỗi, Chờ review
Ngày upload	Khoảng ngày
Đã áp dụng	Lọc chứng từ đã/chưa apply vào lô hàng

Trạng thái trích xuất:

Trạng thái	Mô tả
Đang xử lý	AI đang OCR và phân tích
Đã trích xuất	Dữ liệu sẵn sàng, có thể apply
Cần review	AI không chắc một số trường — cần người dùng xác nhận
Lỗi	File hỏng, mật khẩu, hoặc định dạng không hỗ trợ

🔍

Danh sách chứng từ với trạng thái trích xuất và nút apply

Xử lý lại tài liệu lỗi hàng loạt

Khi có chứng từ ở trạng thái Lỗi, nút "Xử lý lại tài liệu lỗi" hiện ngay trên thanh công cụ danh sách. Bấm vào → hộp thoại xác nhận cho biết sẽ đưa lại tối đa 50 chứng từ đang lỗi vào hàng đợi trích xuất.

• Nếu số chứng từ lỗi nhiều hơn 50, bấm lại nút sau khi đợt đầu xử lý xong để tiếp tục phần còn lại.
• Sau khi xác nhận, hệ thống báo số lượng đã đưa vào hàng đợi (ví dụ: "Đã đưa 32/32 vào hàng đợi").

🔬 Trích xuất

TKHQ hiển thị toàn bộ dữ liệu AI đọc được theo từng trường — bạn xem, chỉnh sửa inline và xác nhận trước khi áp dụng vào tờ khai.

Xem dữ liệu AI đã trích xuất từ chứng từ — chỉnh sửa và xác nhận trước khi dùng.

Dữ liệu trích xuất từ Invoice:

Trường	Ví dụ
Số Invoice	INV-2026-00142
Ngày phát hành	2026-05-20
Người bán	ABC Trading Co., Ltd
Người mua	XYZ Import JSC
Tổng giá trị	USD 12,500.00
Điều kiện thanh toán	T/T 30 days
Dòng hàng	Tên, HS gợi ý, số lượng, đơn giá, thành tiền

Chỉnh sửa inline

Click vào bất kỳ trường nào để sửa trực tiếp. Thay đổi được lưu và dùng khi apply vào tờ khai.

Chi phí trích xuất: ~1.500 token/trang PDF phức tạp (ảnh scan), ~300 token/trang PDF có text layer.

🔍

Dữ liệu trích xuất từ Invoice — chỉnh sửa inline trước khi apply

🔗 Apply to Shipment

TKHQ ánh xạ dữ liệu từ chứng từ sang đúng trường của lô hàng — bạn xem preview mapping, điều chỉnh nếu cần, rồi xác nhận một lần.

Áp dụng dữ liệu chứng từ vào lô hàng hoặc booking container.

Cách apply:

1. Từ trang chi tiết chứng từ → click Apply to Shipment
2. Chọn lô hàng đích (hoặc tạo mới)
3. Xem preview mapping: trường nào từ chứng từ → điền vào trường nào của lô hàng
4. Điều chỉnh nếu cần → click Xác nhận apply

Ví dụ mapping EIR → Container:

Trường từ EIR	Điền vào Container
Số container	containerNumber
Số lệnh	sealNumber
Loại/size	containerType
Ngày gate-out	gateOutDate
Tình trạng	damageNote

Không override dữ liệu đã có

Nếu trường đích đã có dữ liệu, hệ thống hỏi trước khi ghi đè. Chọn Giữ nguyên hoặc Ghi đè.

🔍

Preview mapping trường từ EIR vào Container trước khi xác nhận

📤 Xuất dữ liệu

Xuất dữ liệu đã trích xuất ra Excel hoặc JSON để tích hợp với hệ thống khác.

Định dạng xuất:

• Excel (.xlsx) — mỗi sheet là một loại chứng từ, có header chuẩn
• JSON — cấu trúc đầy đủ, dùng cho API integration
• CSV — cho import vào ERP/phần mềm kế toán

Cách xuất:

1. Chọn một hoặc nhiều chứng từ (checkbox)
2. Click Xuất → chọn định dạng
3. File download về máy

Xuất hàng loạt

Chọn Tất cả và lọc theo ngày/loại trước khi xuất — tránh xuất toàn bộ lịch sử không cần thiết.

🧠 Extraction cache — idempotency

Hệ thống cache kết quả trích xuất để tránh gọi AI lặp lại cho cùng một file:

Cache key được tính từ:

sha256(file_content) : mimeType : declarationType : documentType : bookingType : v1

• Cùng file, cùng context → trả kết quả cache ngay, không tốn token
• Cache TTL: 7 ngày kể từ lần trích xuất cuối
• Dọn dẹp cache hàng ngày lúc 02:00 để xoá bản ghi hết hạn

Khi nào cache bị bypass:

Tình huống	Hành vi
Đổi bookingType (Import → Export)	Re-extract (cache key thay đổi)
Upload lại cùng file	Trả cache (cache key giống)
Nhấn "Trích xuất lại"	Force bypass cache, gọi AI lại
File bị sửa trước khi upload	Re-extract (sha256 khác)

Tiết kiệm token với cache

Nếu cần test nhiều lần với cùng chứng từ, không cần nhấn "Trích xuất lại" — cache sẽ trả kết quả tức thì và không tốn token.

🔍 Các chiến lược trích xuất theo loại chứng từ

Mỗi loại chứng từ dùng một strategy khác nhau để tối ưu độ chính xác:

Loại chứng từ	Strategy	Đặc điểm
Commercial Invoice	InvoiceStrategy	Trích xuất parties, goods list, value, incoterm
Packing List	PackingListStrategy	Tập trung vào dims, weight, packageCount per item
Bill of Lading	BillOfLadingStrategy	vessel, voyage, POL/POD, ETD/ETA, containerList
Shipping Instruction	ShippingInstructionStrategy	SI cutoff, booking reference, cargo details
VAT Invoice	VatInvoiceStrategy	MST, tax amount, đơn vị tính VN
Certificate of Origin	CertOfOriginStrategy	originCountry, FTA form type, HS codes
Contract	ContractStrategy	parties, payment terms, validity period
EIR	EirStrategy	containerNumber, sealNumber, GATE event
Export Declaration	ExportDeclarationStrategy	declarant, goods, HS codes
Booking Confirmation	BookingStrategy	bookingNo, carrier, container list, direction

OCR fallback: Nếu PDF không có text layer (scan ảnh), hệ thống dùng Tesseract OCR với auto-detect xoay ảnh — sau đó mới chạy AI extract trên text đã OCR.

📊 Content pipeline theo định dạng file

Định dạng	Pipeline xử lý
PDF (có text layer)	Extract text trực tiếp → AI
PDF (scan)	Tesseract OCR → AI
JPEG/PNG/TIFF	Resize → AI vision model trực tiếp
XLSX	Chuyển thành Markdown table → AI
DOCX	mammoth.js → HTML → text → AI

Tesseract tự phát hiện góc xoay của ảnh (orientation detection) — không cần xoay ảnh trước khi upload.

🔗 Apply vào Tờ khai hải quan

Ngoài Apply to Shipment, chứng từ còn có thể apply vào Tờ khai hải quan:

• Từ trang tạo tờ khai (Bước 1) → upload chứng từ
• Hoặc từ chi tiết tờ khai → tab Chứng từ → Thêm và apply
• Xung đột khi nhiều chứng từ cung cấp dữ liệu khác nhau → hộp thoại resolve conflict

🔗 Áp dụng Hợp đồng và Tờ khai xuất

Ngoài Invoice / B/L, hai loại chứng từ sau có cách áp dụng riêng:

Hợp đồng (Contract): khi áp dụng, hệ thống điền đối tác cho lô hàng liên kết. Bạn phải xác nhận đối tác trước — chọn từ gợi ý khớp mã số thuế hoặc tạo đối tác mới. Hệ thống không tự tạo và không tự chọn đối tác thay bạn; nếu lô hàng đã có đối tác khác, hệ thống bỏ qua chứ không ghi đè.

Tờ khai xuất (Export Declaration): áp dụng để tạo một tờ khai xuất khẩu nháp từ chứng từ, đồng thời gắn chứng từ nguồn vào tờ khai đó. Áp lại cùng chứng từ không tạo tờ khai trùng.

Cần gói Khai báo

Tạo tờ khai từ chứng từ yêu cầu workspace có gói Khai báo hải quan. Nếu chưa có gói, thao tác này bị chặn.

🔗 Chứng từ được dùng ở tờ khai nào

Trên trang chi tiết một chứng từ, khi chứng từ đã được dùng trong tờ khai, một nhãn "Dùng trong N tờ khai" hiện ra. Bấm vào nhãn để xem danh sách các tờ khai đang dùng chứng từ này và mở nhanh sang từng tờ khai.