Hỗ trợ · Tiện ích đồng bộ hóa đơn TCT
Không đồng bộ được hóa đơn điện tử TCT? Cách xử lý
Quy trình xử lý khi tiện ích Kế Toán 365 không đồng bộ / không tải được hóa đơn từ cổng Thuế hoadondientu.gdt.gov.vn: phiên hết hạn, cổng Thuế từ chối 403, không kết nối được backend, sai API key.
Hiểu luồng đồng bộ — để biết lỗi nằm ở đâu
Mỗi lần bấm Đồng bộ, tiện ích chạy qua 2 chặng. Lỗi luôn rơi vào một trong hai.
Lấy hóa đơn từ Cổng Thuế
Đọc phiên đăng nhập → tìm tab cổng Thuế → lấy danh sách hóa đơn → tải file XML từng hóa đơn.
Thông báo nhắc “cổng Thuế / phiên / đăng nhập” = lỗi ở đây.
Đẩy về phần mềm Kế Toán 365
Gửi từng hóa đơn về backend (kèm API key) → backend chống trùng và ghi sổ.
Thông báo nhắc “backend / API key / Kế Toán 365” = lỗi ở đây.
Kiểm tra 30 giây (giải quyết ~80% ca lỗi)
- 1
Đúng phiên bản?
chrome://extensions → thẻ Kế Toán 365 phải là v0.5.0 trở lên. Cũ hơn thì bấm ⟳ Tải lại.
- 2
Đã mở & đăng nhập cổng Thuế?
Mở hoadondientu.gdt.gov.vn, đăng nhập, thấy được danh sách hóa đơn của mình, GIỮ tab đó mở.
- 3
Đã F5 tab cổng Thuế?
Sau khi cập nhật tiện ích, tải lại (F5) trang Thuế để tiện ích "học" được cơ chế bảo vệ của cổng Thuế.
- 4
Đúng công ty?
Trong popup, chọn đúng công ty cần đồng bộ (kế toán dịch vụ nhiều công ty).
- 5
Backend đã Test kết nối OK?
Cài đặt (⚙) → Test kết nối phải báo xanh "Kết nối thành công".
Bảng tra nhanh
Tìm đúng thông báo bạn thấy trên popup → xem nguyên nhân & cách xử lý.
| Thông báo / triệu chứng | Nguyên nhân | Cách xử lý |
|---|---|---|
| Chưa mở / đăng nhập cổng Thuế | Chưa mở tab Thuế · chưa đăng nhập · phiên hết hạn (~24h) | Mở hoadondientu.gdt.gov.vn, đăng nhập, giữ tab mở → Thử lại. |
| Cổng Thuế TỪ CHỐI yêu cầu (401/403) | Phiên hết hạn thật, hoặc lớp chống-bot của cổng Thuế chặn | Đọc kỹ dòng 🔎 Máy chủ Thuế trả về ngay dưới thông báo — xem Chặng A bên dưới. |
| Lỗi TCT API 5xx | Máy chủ cổng Thuế đang lỗi/quá tải | Chờ 5–15 phút rồi thử lại. Không phải lỗi tiện ích. |
| Chưa nhập API key | Chưa dán API key vào tiện ích | Cài đặt (⚙) → dán API key lấy từ phần mềm Kế Toán 365. |
| API key không đúng hoặc đã đổi | API key sai / đã bị đổi trong Kế Toán 365 | Lấy lại key mới → dán lại → Lưu. |
| KHÔNG kết nối được backend | Sai URL · đổi máy chủ (VPS) · hết chứng chỉ SSL | Kiểm tra Backend URL = https://sell-365.vn; mở thẳng trang đó xem còn chạy/ổ khóa SSL không. |
| Chạy xong nhưng có hóa đơn "failed" | Vài hóa đơn lỗi khi ghi sổ backend | Đồng bộ lại (an toàn, không trùng). Nếu lặp lại → báo kỹ thuật kèm số hóa đơn. |
| Popup đứng im / xoay mãi | Tab cổng Thuế bị đóng giữa chừng · mạng chập chờn | Đóng popup, mở lại, Thử lại (giữ tab Thuế mở). |
Lỗi phía Cổng Thuế
Bí quyết: luôn đọc dòng 🔎 Máy chủ Thuế trả về ngay dưới thông báo — nó cho biết chính xác vì sao.
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
| "Chưa mở / đăng nhập cổng Thuế" | Tiện ích không thấy phiên đăng nhập hợp lệ (không có tab Thuế, chưa đăng nhập, hoặc phiên hết). | 1) Mở hoadondientu.gdt.gov.vn → đăng nhập. 2) Vào Tra cứu, thấy được hóa đơn = phiên OK. 3) Giữ tab mở → Thử lại. 4) Còn lỗi: đăng xuất rồi đăng nhập lại. |
| 403 — "Hệ thống phát hiện hành vi không hợp lệ" | Lớp chống-bot của cổng Thuế chặn vì tiện ích chưa "học" được cơ chế bảo vệ (thường do chưa tải lại trang Thuế sau khi cập nhật). | 1) Qua tab Thuế nhấn F5 (đăng nhập lại nếu cần, giữ tab mở). 2) Bấm Tìm kiếm trên trang Thuế 1 lần. 3) Quay lại popup → Thử lại. 4) Còn lỗi mà đuôi ghi [chưa học được header...] → làm lại bước 1–2. |
| 401 — phiên hết hạn thật | Cookie phiên cổng Thuế hết (~24h) hoặc đã đăng xuất. Dòng 🔎 ghi "unauthorized/phiên/token". | Đăng nhập lại cổng Thuế → giữ tab mở → Thử lại. |
| "Lỗi TCT API" (5xx) | Máy chủ Thuế lỗi/quá tải tạm thời. | Chờ 5–15 phút, thử lại. Không phải lỗi tiện ích. |
| "Lỗi TCT API" (4xx) | Tham số truy vấn sai / endpoint cổng Thuế thay đổi. | Báo kỹ thuật kèm nội dung dòng lỗi. |
| "executeScript: ..." | Tab cổng Thuế bị đóng giữa chừng khi đang đồng bộ. | Mở lại tab cổng Thuế, giữ mở, Thử lại. |
Lỗi phía Kế Toán 365 (backend)
Các lỗi liên quan tới địa chỉ backend, API key và việc ghi sổ.
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
| "Chưa nhập API key" / "Chưa cấu hình backend" | Thiếu API key hoặc Backend URL. | Cài đặt (⚙): Backend URL = https://sell-365.vn; API key lấy ở Kế Toán 365 → 🧾 HĐ điện tử TCT → 🔑 API key Extension (mỗi công ty 1 key) → Lưu → Test kết nối. |
| "KHÔNG kết nối được backend" (status 0) | Không tới được máy chủ: sai URL, đổi VPS, hoặc hết/thiếu SSL. | 1) Kiểm tra Backend URL đúng https, không thừa dấu /. 2) Mở thẳng https://sell-365.vn xem có lên + ổ khóa SSL. 3) Nếu "Không bảo mật"/không vào được → báo kỹ thuật. |
| "API key không đúng hoặc đã đổi" (401) | Key bị đổi/thu hồi, hoặc dán nhầm key công ty khác. | Lấy key mới trong Kế Toán 365 → dán lại đúng công ty → Lưu. |
| "Lỗi backend 5xx" | Máy chủ Kế Toán 365 lỗi. | Chờ rồi đồng bộ lại (đã có chống trùng). Lặp lại → báo kỹ thuật. |
| Một số hóa đơn "failed" | Vài hóa đơn lỗi định dạng/dữ liệu, hoặc backend lỗi tạm. | Tiện ích đã tự thử lại 3 lần với lỗi tạm. Đồng bộ lại an toàn (chống trùng theo nội dung XML). 4xx dai dẳng → báo kỹ thuật kèm số hóa đơn. |
Khi cần báo kỹ thuật — gửi kèm gì?
Khi đã làm hết các bước mà vẫn lỗi, hãy chụp màn hình 4 thông tin sau:
- Phiên bản tiện ích (chrome://extensions → thẻ Kế Toán 365).
- Toàn bộ thông báo trên popup — đặc biệt dòng
🔎 Máy chủ Thuế trả vềvà đuôi[đã gửi kèm...]. - Lịch sử đồng bộ trong popup (dòng lỗi + thời gian).
- Nhật ký lỗi: chrome://extensions → thẻ Kế Toán 365 → nút Lỗi → dòng
[TCT]mới nhất.
Mẹo lấy log sạch: bấm “Lỗi → Xóa tất cả” trước, rồi Thử lại đồng bộ, rồi mới vào “Lỗi” chụp — chỉ còn đúng lỗi của lần thử này.
Câu hỏi thường gặp
Đồng bộ lại nhiều lần có bị trùng hóa đơn không?
Không. Backend chống trùng theo nội dung hóa đơn (mã băm XML) — hóa đơn đã có sẽ tính là "duplicate", không ghi lại.
Có bị sót hóa đơn không?
Không. Tiện ích lấy theo trang (tối đa 50 hóa đơn/trang) và tự lật hết các trang trong khoảng ngày đã chọn.
Dùng trên điện thoại được không?
Không. Đây là tiện ích Chrome, chỉ chạy trên trình duyệt Chrome máy tính. Chrome trên điện thoại không hỗ trợ tiện ích.
Bao lâu phải đăng nhập lại cổng Thuế?
Phiên cổng Thuế thường hết sau khoảng 24 giờ hoặc khi đăng xuất. Hết phiên thì chỉ cần đăng nhập lại, không liên quan tới tiện ích.
Vẫn 403 sau khi làm hết các bước thì sao?
Chụp toàn bộ thông báo trên popup (đặc biệt dòng 🔎 Máy chủ Thuế trả về và đuôi [đã gửi kèm...]) cùng phiên bản tiện ích, rồi gửi kỹ thuật. Có thể cổng Thuế vừa đổi cơ chế bảo vệ.
Vẫn cần hỗ trợ?
Gửi cho chúng tôi các thông tin ở mục “báo kỹ thuật” phía trên — đội hỗ trợ sẽ xử lý nhanh.