API hóa đơn điện tử: cổng thuế có API công khai không

Không có API công khai để tra cứu hóa đơn mua vào. Cổng thuế không phát hành tài liệu API, không cấp khóa truy cập cho bên thứ ba, và bắt buộc nhập captcha để lấy phiên đăng nhập mới — đây là ràng buộc khiến không tích hợp nào chạy hoàn toàn tự động mà không cần người can thiệp. Cần phân biệt rõ với API của nhà cung cấp hóa đơn điện tử, thứ có thật nhưng dành cho hóa đơn bán ra của chính bạn.

1. Ba thứ hay bị gọi chung là "API hóa đơn điện tử"
2. Bốn ràng buộc kỹ thuật, ai làm cũng gặp
3. Hai bảng kê còn lệch cột nhau
4. Trạng thái hóa đơn: bẫy khi so chuỗi
5. Hóa đơn đổi trạng thái sau khi đã tải
6. Vậy tích hợp với phần mềm kế toán bằng cách nào
7. Tóm tắt cho người quyết định kỹ thuật
8. Căn cứ
9. Xem thêm

Ba thứ hay bị gọi chung là "API hóa đơn điện tử"#

Nhầm lẫn thường đến từ dòng đầu. Doanh nghiệp đã tích hợp phần mềm bán hàng với nhà cung cấp hóa đơn để tự động phát hành hóa đơn bán ra, rồi cho rằng chiều ngược lại — lấy hóa đơn mua vào — cũng làm được tương tự. Hai chiều này đi qua hai hệ thống hoàn toàn khác nhau.

Nhắc lại cho rõ: hóa đơn mua vào của bạn là hóa đơn bán ra của người khác, nằm trên hệ thống của cơ quan thuế chứ không nằm ở nhà cung cấp phần mềm của bạn.

Bốn ràng buộc kỹ thuật, ai làm cũng gặp#

Đây là phần đáng giá nhất nếu bạn đang cân nhắc tự xây tích hợp.

1. Captcha bắt buộc khi lấy phiên mới. Mỗi lần lấy phiên mới bằng mã số thuế và mật khẩu tra cứu, cổng thuế bắt nhập captcha (ảnh SVG). Không có đường vòng hợp lệ nào. Nghĩa là không tự động hóa được 100% phần đăng nhập — mọi giải pháp đều phải có bước con người nhập captcha ở đâu đó.

2. Phiên là JWT có hạn. Token mang thời điểm hết hạn bên trong. Cách làm an toàn là coi phiên hết hạn sớm hơn mốc thật khoảng 5 phút, để một lượt tải dài không bị đứt giữa chừng. Nếu công cụ có lưu mật khẩu, hãy xóa phiên đã lưu ngay khi mật khẩu thay đổi — eHoaDon làm việc này khi bạn cập nhật mật khẩu công ty, và lần đồng bộ sau sẽ hỏi captcha lại.

3. Mỗi lượt gọi chỉ lấy được tối đa 01 tháng. Muốn tra cả năm thì phải tự cắt kỳ thành 12 tháng, và nhân đôi vì có hai loại hóa đơn tra ở hai đường dẫn khác nhau — hóa đơn điện tử thường và hóa đơn khởi tạo từ máy tính tiền. Một kỳ 1 năm là 24 lượt tải danh sách, chưa tính phần chi tiết. Xem Giới hạn kỳ tra cứu hóa đơn một tháng.

4. Danh sách không chứa dòng hàng hóa. Bảng kê tải về chỉ có số tổng của mỗi hóa đơn — không có mặt hàng, đơn vị tính, số lượng, đơn giá, thuế suất từng dòng. Muốn có chi tiết thì phải gọi riêng cho từng hóa đơn một.

Ràng buộc thứ tư quyết định khối lượng công việc thật. Một kỳ 1.000 hóa đơn nghĩa là 1.000 lượt gọi chi tiết, không phải 1. Đây luôn là phần chậm nhất, chứ không phải phần tải danh sách như nhiều người tưởng.

Hai bảng kê còn lệch cột nhau#

Hai file chỉ trùng 7 cột đầu (A–G); từ cột H trở đi lệch, nên cột Trạng thái hóa đơn và Kết quả kiểm tra hóa đơn nằm ở R/S với hóa đơn thường nhưng P/Q với hóa đơn máy tính tiền. Hardcode chỉ số cột rồi dùng chung cho hai loại là đọc nhầm đúng hai cột quan trọng nhất — phân tích đầy đủ: Tự viết script tải hóa đơn từ trang thuế.

Trạng thái hóa đơn: bẫy khi so chuỗi#

Hai trường trạng thái trên mỗi hóa đơn:

• Kết quả kiểm tra hóa đơn — 9 giá trị, từ "Cục Thuế đã nhận" đến "Cục Thuế đã nhận hóa đơn có mã khởi tạo từ máy tính tiền". Chỉ 3 giá trị là hóa đơn dùng được: "Đã cấp mã hóa đơn", "Cục Thuế đã nhận không mã" và "Cục Thuế đã nhận hóa đơn có mã khởi tạo từ máy tính tiền"
• Trạng thái hóa đơn — 6 giá trị: mới, thay thế, điều chỉnh, đã bị thay thế, đã bị điều chỉnh, đã bị hủy

Một bẫy chữ nghĩa cần biết trước khi so chuỗi: cùng một giá trị nhưng văn bản trong file Excel khác văn bản hiển thị trên web. Kết quả kiểm tra của hóa đơn không mã ghi là "Tổng cục thuế đã nhận không mã" trong file tải về, trong khi giao diện web ghi "Cục Thuế đã nhận không mã". Cơ quan đã đổi tên từ 01/3/2025 nhưng chuỗi trong file bảng kê vẫn giữ tên cũ. So chuỗi cứng giữa hai nguồn là hỏng.

Bảng đầy đủ hai nhóm mã: Trạng thái xử lý hóa đơn (ttxly) là gì.

Hóa đơn đổi trạng thái sau khi đã tải#

Người bán có thể hủy hoặc thay thế hóa đơn nhiều tháng sau ngày lập, và dữ liệu đã tải không tự cập nhật. Cổng thuế lọc theo ngày lập hóa đơn, nên hóa đơn lập tháng 3 bị hủy vào tháng 7 chỉ lộ ra khi tra lại tháng 3 — tích hợp tự xây cần vòng quét lại các tháng cũ định kỳ. Xem Hóa đơn bị hủy sau khi đã kê khai.

Khóa nhận dạng một hóa đơn khi đối chiếu giữa hai lần tải: mã số thuế người bán + ký hiệu mẫu số + ký hiệu hóa đơn + số hóa đơn, theo từng loại hóa đơn. Số hóa đơn một mình không đủ để phân biệt.

Vậy tích hợp với phần mềm kế toán bằng cách nào#

Thực tế hiện nay, cách phổ biến và ổn định nhất vẫn là qua file Excel: tra cứu và bóc tách dữ liệu ở một nơi, xuất file mỗi dòng một mặt hàng, rồi nạp vào phần mềm kế toán theo định dạng phần mềm đó nhận.

Nói thẳng về sản phẩm: eHoaDon không có API công khai và không tích hợp trực tiếp với phần mềm kế toán. Bề mặt tích hợp là file Excel xuất ra — 1 sheet, sắp theo ngày lập tăng dần, chọn một trong hai kiểu: Chi tiết mặt hàng (27 cột, mỗi dòng một mặt hàng) hoặc Tổng quan (19 cột, mỗi hóa đơn một dòng). Cấu trúc file: Xuất Excel hóa đơn mua vào đầy đủ dòng hàng hóa.

Nếu bạn đang cân nhắc tự xây so với dùng công cụ có sẵn, bốn ràng buộc ở trên là thứ nên đưa vào bảng so sánh trước tiên — chúng không mất đi dù chọn hướng nào. Các tiêu chí còn lại: Chọn phần mềm tra cứu hóa đơn mua vào và Tự viết script tải hóa đơn từ trang thuế.

Tóm tắt cho người quyết định kỹ thuật#

• Không có API công khai cho hóa đơn mua vào — mọi giải pháp đều đi qua giao diện cổng thuế
• Captcha bắt buộc, không tự động hóa 100% được phần đăng nhập
• Phiên là JWT có hạn, nên coi hết hạn sớm hơn mốc thật vài phút
• Tra tối đa 1 tháng mỗi lượt, 2 loại hóa đơn, nên 1 năm là 24 lượt tải danh sách
• Danh sách không có dòng hàng hóa, phải gọi chi tiết từng hóa đơn
• Hai bảng kê lệch cột từ cột H, cột trạng thái ở R/S so với P/Q
• Muốn thấy hóa đơn đổi trạng thái phải tra lại đúng tháng ngày lập
• Tích hợp với phần mềm kế toán thực tế đi qua file Excel

Hóa đơn thương mại điện tử (mẫu số 7, ký tự X) nghe như hóa đơn bán qua sàn, nhưng thực ra là hóa đơn thương mại của người xuất khẩu: Hóa đơn thương mại điện tử: mẫu số 7 và ký tự X.

Căn cứ#

• Chương IV Nghị định 254/2026/NĐ-CP (hiệu lực 01/7/2026) — cơ sở dữ liệu hóa đơn điện tử và việc tra cứu, cung cấp, sử dụng thông tin hóa đơn điện tử
• Điều 4 và Phụ lục I Thông tư 91/2026/TT-BTC — mẫu số hóa đơn là một chữ số từ 1 đến 9; ký hiệu hóa đơn gồm 6 ký tự, ký tự thứ tư là một trong T D L M N B G H X F; mẫu số 7 và ký tự X là hóa đơn thương mại điện tử
• Khoản 3 Điều 8 Nghị định 254/2026/NĐ-CP — hóa đơn thương mại điện tử áp dụng với người xuất khẩu hàng hóa, cung cấp dịch vụ ra nước ngoài đáp ứng điều kiện chuyển dữ liệu hóa đơn thương mại bằng phương thức điện tử đến cơ quan thuế
• Quyết định 381/QĐ-BTC (ban hành 26/02/2025, hiệu lực 01/3/2025) — đổi tên Tổng cục Thuế thành Cục Thuế thuộc Bộ Tài chính; đây là lý do văn bản trạng thái trong file bảng kê và trên giao diện web khác nhau

Các ràng buộc kỹ thuật nêu trong bài là hành vi quan sát được của cổng thuế tại thời điểm viết, không phải quy định trong văn bản pháp luật — cổng có thể thay đổi mà không thông báo trước.

Xem thêm#

• Tự viết script tải hóa đơn từ trang thuế
• Chọn phần mềm tra cứu hóa đơn mua vào: 8 tiêu chí
• Trạng thái xử lý hóa đơn (ttxly) là gì