Chuyển tới nội dung chính
Phiên bản: 1.7.0

Tạo hóa đơn

POST /<provider>/create-invoice

API dùng để tạo hóa đơn mới lên hệ thống của nhà cung cấp thông qua Gateway.

Headers​

NameRequiredDescription
Authorization✅Bearer token_truy_cap
Content-Type✅application/json
X-Tax-Code✅Mã số thuế của người bán.

Request Body​

NameRequiredDescription
langNgôn ngữ hệ thống thông báo lỗi, mặc định là tiếng Việt ('en', 'vi').
inv.serial✅Ký hiệu hóa đơn. Ví dụ: '1CM25MTS'.
inv.invoice_date✅Ngày phát hành hóa đơn (timestamp). Ví dụ: '2025-08-12T05:06:13'.
inv.currency✅Đơn vị tiền tệ ('VND', 'USD').
inv.ex_rate✅Tỷ giá. Ví dụ: 1.
inv.buyer_name✅Tên người mua.
inv.buyer_legal_name✅Tên đơn vị mua.
inv.buyer_taxMã số thuế người mua.
inv.buyer_address✅Địa chỉ người mua.
inv.buyer_phone_numberKhông (only MISA, FPT, Viettel)Số điện thoại người mua.
inv.buyer_emailEmail người mua. Ví dụ: '[email protected]'.
inv.buyer_id_numberKhông (only 1Invoice, MISA)Số định danh cá nhân người mua.
inv.buyer_bank_accountSố tài khoản người mua.
inv.buyer_bank_nameTên ngân hàng của stk.
inv.payment_method✅Hình thức thanh toán (TM, CK, TM/CK, DTCN, KTT, TTD, HBT, TQL, L/C, TTR, TM/CK/BTCN).
inv.discountSố tiền chiết khấu.
inv.sum_v✅Tổng tiền chưa thuế, đã chiết khấu (đã quy đổi VNĐ).
inv.sum_sale_v✅Tổng tiền hàng chưa thuế, chưa chiết khấu (đã quy đổi VNĐ).
inv.vat_vCó nếu là hóa đơn GTGTTổng tiền thuế (đã quy đổi VNĐ).
inv.total_v✅Thành tiền sau thuế (đã quy đổi VNĐ).
inv.total_v_in_words✅Thành tiền sau thuế bằng chữ (VNĐ).
inv.seqSố đơn hàng.
inv.sid✅Mã đơn hàng theo merchant. Không được phép trùng.
inv.sum✅Tổng tiền chưa thuế, đã chiết khấu (nguyên tệ).
inv.sum_sale✅Tổng tiền hàng chưa thuế, chưa chiết khấu (nguyên tệ).
inv.vatCó nếu là hóa đơn GTGTTổng tiền thuế nguyên tệ.
inv.total✅Tổng tiền thanh toán bao gồm tiền thuế nguyên tệ.
inv.form✅Mẫu hóa đơn đăng ký sử dụng trên hệ thống.
inv.aunKhông (only FPT)Xác định phương thức quản lý số hóa đơn sẽ do hệ thống nào cấp số: DN tự quản lý cấp số ('aun': 1, bắt buộc phải có số hóa đơn tại thẻ 'seq'); eInvoice tự động cấp số ('aun': 2).
inv.signKhông (only FPT)Sử dụng đối với hóa đơn xuất hoàn trả ('sign': -1: đánh dấu hóa đơn xuất hoàn trả; 'sign': 1 hoặc không có thẻ: hóa đơn thông thường).
inv.type_refKhông (only FPT)Thẻ xác định loại hóa đơn đang sử dụng (1: Hóa đơn theo TT78; bỏ trống: Hóa đơn theo TT32).
inv.stax✅Mã số thuế người bán. Ví dụ: '2392190986'.
inv.typeCó (only FPT, Vietel)Loại hóa đơn. Ví dụ: '01GTKT'.
inv.is_send_mailCó gửi email khi phát hành thành công không.
inv.receiver_nameTên người nhận email.
inv.receiver_emailĐịa chỉ nhận email, phân tách bởi dấu ; (Chỉ thực hiện ở Product).
inv.items[].line✅Số thứ tự dòng hàng hóa.
inv.items[].type✅Loại hàng hóa (1: Thường, 2: Khuyến mại, 3: Chiết khấu, 4: Ghi chú, 5: Hàng đặc thù vận tải).
inv.items[].codeMã hàng hóa.
inv.items[].nameTên hàng hóa.
inv.items[].unitĐơn vị hàng hóa.
inv.items[].quantitySố lượng hàng hóa.
inv.items[].priceĐơn giá hàng hóa.
inv.items[].perdiscountTỷ lệ % chiết khấu.
inv.items[].amtdiscountSố tiền chiết khấu.
inv.items[].amountThành tiền từng dòng hàng hóa dịch vụ.
inv.items[].amountnThành tiền sau chiết khấu (= amount - amtdiscount).
inv.items[].vrtCó nếu là hóa đơn GTGTLoại thuế suất, giá trị tùy thuộc vào nhà cung cấp ('0', '5', '10').
inv.items[].vatCó nếu là hóa đơn GTGTSố tiền VAT từng hàng hóa.
inv.items[].totalTổng tiền bao gồm VAT từng hàng hóa.
inv.tax_rate_info[].vrtCó nếu là hóa đơn GTGT (only MISA, Viettel)Tổng hợp loại thuế suất: KCT(MISA) || -1 (Viettel): chịu thuế; KKKNT (MISA) || -2 (Viettel): kê khai nộp thuế; 0%: thuế suất 0%; 5%: thuế suất 5%; 8%: thuế suất 8%; 10%: thuế suất 10%; KHAC:x%: loại thuế suất khác (Ví dụ: KHAC:3.5%).
inv.tax_rate_info[].amountnCó nếu là hóa đơn GTGT (only MISA, Viettel)Tổng tiền trước thuế của dòng hàng theo nhóm thuế suất.
inv.tax_rate_info[].vatCó nếu là hóa đơn GTGT (only MISA, Viettel)Tổng tiền thuế của dòng hàng.

Lưu ý theo nhà cung cấp​

Sự khác nhau về giá trị theo nhà cung cấp trong một số trường khi tạo hóa đơn​

Tên trường1InvoiceFPTMisaViettel
inv.serialBắt buộcKhông bắt buộcBắt buộcBắt buộc
inv.invoice_dateBắt buộcBắt buộcBắt buộcKhông bắt buộc
inv.staxTruyền MSTTruyền MSTTruyền MSTTruyền chuỗi rỗng ""
inv.payment_methodKhông bắt buộc phải là "TM/CK", "CK"... mà có thể tùy biến ví dụ "QR", "CARD"Bắt buộc phải là "TM", "CK", "TM/CK"....Không bắt buộc phải là "TM/CK", "CK"... mà có thể tùy biến ví dụ "QR", "CARD"Không bắt buộc phải là "TM/CK", "CK"... mà có thể tùy biến ví dụ "QR", "CARD"
inv.form"1""1" (không truyền trường này nếu đã truyền serial)""template_code trả từ danh sách ký hiệu hóa đơn
inv.typeKhông bắt buộcBắt buộcKhông bắt buộcBắt buộc
inv.items[].type1 Tính chất hàng hóa:
- Hàng hóa dịch vụ (giá trị tchat là 1)
- Khuyến mại (giá trị tchat là 2)
- Chiết khấu thương mại (giá trị tchat là 3)
- Ghi chú/ diễn giải (giá trị tchat là 4)		"" Hình thức hàng hóa có 4 loại:
- MT : Ghi chú, diễn giải
- CK : Chiết khấu thương mại
- KM : Khuyến mãi
- Truyền rỗng : Thông thường		1 Tính chất hàng hóa:
1: Hàng hóa thường
2: Khuyến mại
3: Chiết khấu
4: Ghi chú/diễn giải
5: Hàng hóa đặc thù vận tải		"" - Null hoặc 1- Hàng Hóa (Sinh STT, bắt buộc phải nhập số lượng, đơn giá)
- 2: Ghi chú (Không sinh STT và không cộng tiền vào tổng tiền thanh toán)
- 3: Chiết khấu (Không sinh STT, không cần nhập số lượng, đơn giá và thêm isIncreaseItem = false để xác định giảm tiền)
- 4: Phí khác (Không sinh STT, không nhập số lượng, đơn giá)
- 5: Khuyến mại (Sinh STT, bắt buộc phải nhập số lượng, đơn giá)
- 6: Hàng hóa đặc trưng, nếu truyền hàng hóa đặc trưng (ND 70) thì các trường thông tin bắt buộc xem danh sách bên dưới
inv.items[].vrt"8", "10" …
Truyền các giá trị cố định sau:
10: Thuế suất 10%
8: Thuế suất 8%
5: Thuế suất 5%
0: Thuế suất 0%
-1: Không chịu thuế
-2: Không kê khai nộp thuế
Trường hợp phát sinh thêm thuế suất khác ngoài danh sách liên hệ với 1Invoice
Bắt buộc truyền nếu tchat là 1,2,3
Không bắt buộc nếu tchat là 4		"8", "10" …
Loại thuế suất : ( 0, 5, 8, 10, -1, -2)
+ 0: thuế suất 0%
+ 5: thuế suất 5%
+ 8: thuế suất 8%
+ 10: thuế suất 10%
+ -1: Không chịu thuế
+ -2: Không kê khai nộp thuế
Khác 6 loại thuế suất trên: thuế suất Khác		"8%", "10%" …
KCT: chịu thuế
KKKNT: kê khai nộp thuế
0%: thuế suất 0%
5%: thuế suất 5%
8%: thuế suất 8%
10%: thuế suất 10%
KHAC:x%: loại thuế suất khác (Ví dụ: KHAC:3.5%)		"8", "10" …
Thuế suất của hàng hóa, dịch vụ (-2: không thuế, -1: không kê khai, 0: 0%, 5: 5%, 8: 8%, 10: 10%...).

Xuất hóa đơn cho khách lẻ​

Trường1InvoiceFPTMisaViettel
Tên đơn vị (inv.buyer_legal_name)Không bắt buộcBắt buộcKhông bắt buộcKhông bắt buộc
Địa chỉ (inv.buyer_address)Không bắt buộcBắt buộc
Có thể để nội dung: "Khách không lấy hóa đơn"		Không bắt buộcKhông bắt buộc

Response​

NameDescription
data.search_codeMã để người dùng tra cứu hóa đơn
data.seqSố hóa đơn
data.tax_authority_codeMã cơ quan thuế
data.vpidId dùng để xem PDF hoặc ký hóa đơn
data.error_codeMã lỗi nếu có (Có mã lỗi: Tạo Fail, không có mã lỗi: Tạo thành công)
data.transaction_idMã giao dịch nếu có

Lưu ý về kết quả trả về theo nhà cung cấp​

sự khác nhau giữa dữ liệu respone khi tạo hóa đơn (✅: có, ❌: không)

Trường1InvoiceFPTMisaViettel
Mã cơ quan thuế
Mã tra cứu
Số hóa đơn
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/create-invoice' \
--header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \
--header 'x-tax-code: 0106026495-998' \
--header 'Content-Type: application/json' \
--data '{
    "lang": "vi",
    "inv": {
        "serial": "1C25MTS",
        "invoice_date": "2025-08-12T05:06:13",
        "currency": "VND",
        "ex_rate": 1,
        "buyer_name": "Lê Thanh Dũng",
        "buyer_legal_name": "1Invoice - Kiểm thử HĐĐT không mã",
        "buyer_tax": "0106026495-998",
        "buyer_address": "Số nhà 16, ngõ 269/1, đường Giáp Bát, Phường Hoàng Mai, TP Hà Nội",
        "buyer_email": "",
        "payment_method": "QR",
        "buyer_bank_account": "",
        "buyer_bank_name": "",
        "sum_v": 81500,
        "vat_v": 8150,
        "total_v": 89650,
        "type": "01GTKT",
        "sid": "160725-8238-JFSFA122",
        "sum": 81500,
        "vat": 8150,
        "total": 89650,
        "total_v_in_words": "tám mươi chín nghìn sáu trăm năm mươi đồng",
        "form": "1",
        "aun": 2,
        "sign": 1,
        "type_ref": 1,
        "stax": "0106026495-998",
        "items": [
            {
                "line": 1,
                "code": "172",
                "name": "Mì xào trứng",
                "unit": "Phần",
                "quantity": 1,
                "price": 50000,
                "perdiscount": 0,
                "amtdiscount": 0,
                "amount": 50000,
                "amountn":50000,
                "vrt": "10",
                "vat": 5000,
                "total": 55000
            },
            {
                "line": 2,
                "code": "173",
                "name": "Bánh mì ốp la",
                "unit": "Phần",
                "quantity": 1,
                "price": 30000,
                "perdiscount": 0,
                "amtdiscount": 0,
                "amount": 30000,
                "amountn":30000,
                "vrt": "10",
                "vat": 3000,
                "total": 33000
            },
            {
                "line": 3,
                "code": "262",
                "name": "Sticker",
                "unit": "Phần",
                "quantity": 1,
                "price": 1500,
                "perdiscount": 0,
                "amtdiscount": 0,
                "amount": 1500,
                "amountn":1500,
                "vrt": "10",
                "vat": 150,
                "total": 1650
            }
        ]
    }
}'