Phiên bản: 1.5.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

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

Request Body

Name	Required	Description
`lang`		Ngô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_tax`		Mã số thuế người mua.
`inv.buyer_address`	✅	Địa chỉ người mua.
`inv.buyer_phone_number`		Số điện thoại người mua (only MISA, FPT, Viettel).
`inv.buyer_email`		Email người mua.
`inv.buyer_id_number`		Số định danh cá nhân người mua (only M-invoice, MISA).
`inv.buyer_bank_account`		Số tài khoản người mua.
`inv.buyer_bank_name`		Tê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.discount`		Số 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_v`		Tổng tiền thuế (đã quy đổi VNĐ). Có nếu là hóa đơn GTGT.
`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.seq`		Số đơ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.vat`		Tổng tiền thuế nguyên tệ. Có nếu là hóa đơn GTGT.
`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.aun`		Xác định phương thức quản lý số hóa đơn (1: tự quản lý, 2: eInvoice tự động cấp số). (only FPT).
`inv.sign`		Xác định hóa đơn xuất hoàn trả (-1: xuất hoàn trả, 1: thông thường). (only FPT).
`inv.type_ref`		Thẻ xác định loại hóa đơn đang sử dụng (1: TT78). (only FPT).
`inv.stax`	✅	Mã số thuế người bán.
`inv.type`		Loại hóa đơn. Có (only FPT, Vietel).
`inv.is_send_mail`		Có gửi email khi phát hành thành công không.
`inv.receiver_name`		Tê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[].code`		Mã hàng hóa.
`inv.items[].name`		Tên hàng hóa.
`inv.items[].unit`		Đơn vị hàng hóa.
`inv.items[].quantity`		Số lượng hàng hóa.
`inv.items[].price`		Đơn giá hàng hóa.
`inv.items[].perdiscount`		Tỷ lệ % chiết khấu.
`inv.items[].amtdiscount`		Số tiền chiết khấu.
`inv.items[].amount`		Thành tiền từng dòng hàng hóa dịch vụ.
`inv.items[].amountn`		Thành tiền sau chiết khấu (= amount - amtdiscount).
`inv.items[].vrt`		Loại thuế suất. Có nếu là hóa đơn GTGT.
`inv.items[].vat`		Số tiền VAT từng hàng hóa. Có nếu là hóa đơn GTGT.
`inv.items[].total`		Tổng tiền bao gồm VAT từng hàng hóa.
`inv.tax_rate_info[].vrt`		Tổng hợp loại thuế suất. Có nếu là hóa đơn GTGT (only MISA, Viettel).
`inv.tax_rate_info[].amountn`		Tổng tiền trước thuế của dòng hàng theo nhóm thuế suất (only MISA, Viettel).
`inv.tax_rate_info[].vat`		Tổng tiền thuế của dòng hàng (only MISA, Viettel).

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ường	M-invoice & 1Invoice	FPT	Misa	Viettel
inv.serial	Bắt buộc	Không bắt buộc	Bắt buộc	Bắt buộc
inv.invoice_date	Bắt buộc	Bắt buộc	Bắt buộc	Không bắt buộc
inv.stax	Truyền MST	Truyền MST	Truyền MST	Truyền chuỗi rỗng ""
inv.payment_method	Khô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.type	Không bắt buộc	Bắt buộc	Không bắt buộc	Bắt buộc
inv.items[].type	1 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 M-Invoice 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ường	M-invoice & 1Invoice	FPT	Misa	Viettel
Tên đơn vị (inv.buyer_legal_name)	Không bắt buộc	Bắt buộc	Không bắt buộc	Không bắt buộc
Địa chỉ (inv.buyer_address)	Không bắt buộc	Bắt buộc Có thể để nội dung: "Khách không lấy hóa đơn"	Không bắt buộc	Không bắt buộc

Response

Name	Description
`data.search_code`	Mã để người dùng tra cứu hóa đơn
`data.seq`	Số hóa đơn
`data.tax_authority_code`	Mã cơ quan thuế
`data.vpid`	Id dùng để xem PDF hoặc ký hóa đơn
`data.error_code`	Mã 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_id`	Mã 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ường	M-invoice & 1Invoice	FPT	Misa	Viettel
Mã cơ quan thuế	✅	✅	✅	✅
Mã tra cứu	✅	✅	✅	✅
Số hóa đơn	✅	✅	✅	✅

Curl M-Invoice
Curl 1Invoice
Curl Misa
Curl FPT
Response Sample

curl --location 'https://stag-invoice-hub.atomsolution.vn/m-invoice/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": "M-INVOICE - 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
            }
        ]
    }
}'

curl --location 'https://stag-invoice-hub.atomsolution.vn/one-invoice/create-invoice' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY='

curl --location 'https://stag-invoice-hub.atomsolution.vn/misa/create-invoice?type_invoice=icr' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...t059_mSzTqFuqednbgn3oSNiO-50SoQxMg9EOewp228'

curl --location 'https://stag-invoice-hub.atomsolution.vn/fpt/create-invoice' \
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwMzE2ODg3MDk5LmFwaTk5OSIsIm1...'

{
  "data": {
    "search_code": "9A97B32B",
    "seq": 567,
    "tax_authority_code": "M1-25-RV1DV-00000009403"
  },
  "success": true,
  "message": null
}

Tạo hóa đơn

Headers​

Request Body​

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​

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

Response​

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

Headers

Request Body

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

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

Response

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