Định dạng XML Hóa đơn

Tổng quan

XML hóa đơn điện tử hợp lệ (TT78 / Nghị định 123/2020/NĐ-CP) được tạo, ký và gửi hoàn toàn bởi VNPAY (viiAPI). BANA chỉ trao đổi JSON: @nx/invoice dựng request phát hành JSON qua _buildInvoiceRequest và không bao giờ tạo XML nội bộ (không xml2js, không ký XML, không kiểm tra XSD trong BANA).

Cấu trúc bên dưới là schema do GDT quy định mà nhà cung cấp tạo ra, giữ ở đây để tham khảo nhằm hiểu artifact đã phát hành - không phải thứ BANA sinh ra.

@nx/invoice làm gì

Bước	Định dạng	Chủ thể
Request phát hành	JSON	@nx/invoice dựng qua _buildInvoiceRequest, gửi qua @nx/iiapi
Tạo XML hợp lệ	XML (TT78 / Nghị định 123)	VNPAY (nhà cung cấp)
Ký XML + gửi GDT	XML	VNPAY (nhà cung cấp)
Phản hồi nhà cung cấp	JSON	@nx/invoice lưu (invoiceNumber, trạng thái)

Cấu trúc XML

Ví dụ XML

Artifact do nhà cung cấp tạo (VNPAY); chỉ để tham khảo. BANA không dựng cũng không ký XML này.

<?xml version="1.0" encoding="UTF-8"?>
<HDon>
  <DLHDon>
    <TTChung>
      <PBan>2.0.0</PBan>              <!-- Phiên bản XML -->
      <THDon>Hóa đơn GTGT</THDon>     <!-- Tên loại hóa đơn -->
      <KHMSHDon>1</KHMSHDon>          <!-- Mã mẫu -->
      <KHHDon>C25TAA</KHHDon>         <!-- Ký hiệu -->
      <SHDon>00000001</SHDon>         <!-- Số hóa đơn (nhà cung cấp cấp phát) -->
      <NLap>2025-01-20</NLap>         <!-- Ngày lập -->
      <DVTTe>VND</DVTTe>              <!-- Đơn vị tiền tệ -->
      <TGia>1</TGia>                  <!-- Tỷ giá -->
      <HTTToan>TM/CK</HTTToan>        <!-- Hình thức thanh toán -->
    </TTChung>
    <NDHDon>
      <NBan>
        <Ten>Công ty TNHH ABC</Ten>
        <MST>0123456789</MST>
        <DChi>123 Nguyễn Huệ, Q1, TP.HCM</DChi>
      </NBan>
      <NMua>
        <Ten>Khách hàng XYZ</Ten>
        <MST>9876543210</MST>
        <DChi>456 Lê Lợi, Q1, TP.HCM</DChi>
      </NMua>
      <DSHHDVu>
        <HHDVu>
          <TChat>1</TChat>
          <STT>1</STT>
          <THHDVu>Sản phẩm A</THHDVu>
          <DVTinh>Cái</DVTinh>
          <SLuong>2</SLuong>
          <DGia>100000</DGia>
          <ThTien>200000</ThTien>
          <TSuat>10%</TSuat>
        </HHDVu>
      </DSHHDVu>
      <TToan>
        <TgTCThue>200000</TgTCThue>
        <TgTThue>20000</TgTThue>
        <TgTTTBSo>220000</TgTTTBSo>
        <TgTTTBChu>Hai trăm hai mươi nghìn đồng</TgTTTBChu>
      </TToan>
    </NDHDon>
  </DLHDon>
  <DSCKS>
    <NBan>
      <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <!-- Chữ ký số của người bán (phía nhà cung cấp) -->
      </Signature>
    </NBan>
  </DSCKS>
</HDon>

Tham chiếu Trường

Schema do GDT quy định, tạo phía nhà cung cấp. Chỉ để tham khảo.

TTChung (Thông tin chung)

Phần tử	Bắt buộc	Mô tả	Định dạng
PBan	Có	Phiên bản XML	"2.0.0"
THDon	Có	Tên loại hóa đơn	Văn bản
KHMSHDon	Có	Mã mẫu	1-6
KHHDon	Có	Ký hiệu	Tối đa 6 ký tự
SHDon	Có	Số hóa đơn	8 chữ số
MHSo	Có	Mã mẫu số	Mẫu: ##GTKT#/###
NLap	Có	Ngày lập	YYYY-MM-DD
DVTTe	Có	Đơn vị tiền tệ	ISO 4217 (VND)
TGia	Có	Tỷ giá	Số thập phân
HTTToan	Có	Hình thức thanh toán	TM/CK/TM-CK

NBan (Người bán)

Phần tử	Bắt buộc	Mô tả
Ten	Có	Tên công ty
MST	Có	Mã số thuế (10 hoặc 13 chữ số)
DChi	Có	Địa chỉ
SDThoai	Không	Số điện thoại
DCTDTu	Không	Email
STKNHang	Không	Số tài khoản ngân hàng
TNHang	Không	Tên ngân hàng

NMua (Người mua)

Phần tử	Bắt buộc	Mô tả
Ten	Có	Tên khách hàng
MST	Chỉ B2B	Mã số thuế
DChi	Không	Địa chỉ
HVTNMHang	Không	Người liên hệ

HHDVu (Dòng hàng)

Phần tử	Bắt buộc	Mô tả
TChat	Có	Bản chất: 1=Hàng hóa, 2=Dịch vụ
STT	Có	Số dòng
MHHDVu	Không	Mã hàng hóa
THHDVu	Có	Tên hàng hóa
DVTinh	Có	Đơn vị tính
SLuong	Có	Số lượng
DGia	Có	Đơn giá
TLCKhau	Không	Tỷ lệ chiết khấu
STCKhau	Không	Số tiền chiết khấu
ThTien	Có	Thành tiền (trước VAT)
TSuat	Có	Thuế suất VAT

TToan (Tổng cộng)

Phần tử	Bắt buộc	Mô tả
TgTCThue	Có	Tổng tiền trước VAT
TgTThue	Có	Tổng VAT
TgTTTBSo	Có	Tổng cộng (số)
TgTTTBChu	Có	Tổng cộng (chữ)

Thuế suất VAT

Thuế suất	Mã	Mô tả
0%	0%	Hàng xuất khẩu, hàng miễn thuế
5%	5%	Hàng thiết yếu
8%	8%	Thuế suất tiêu chuẩn (giảm tạm thời)
10%	10%	Thuế suất tiêu chuẩn
KCT	KCT	Không chịu thuế VAT
KKKNT	KKKNT	Hàng không kê khai nộp thuế

Trang liên quan

• Invoice Service
• Tích hợp
• Tích hợp iiapi
• Chữ ký Số
• Quyết định