Skip to main content
Version: Next

Create invoice

POST /<provider>/create-invoice

API used to create a new invoice in the provider's system through the Gateway.

Headers​

NameRequiredDescription
Authorization✅Bearer access_token
Content-Type✅application/json
X-Tax-Code✅Seller's tax code.

Request Body​

NameRequiredDescription
langLanguage for system error messages, defaults to Vietnamese ('en', 'vi').
inv.serial✅Invoice serial. Example: '1CM25MTS'.
inv.invoice_date✅Invoice issue date (timestamp). Example: '2025-08-12T05:06:13'.
inv.currency✅Currency ('VND', 'USD').
inv.ex_rate✅Exchange rate. Example: 1.
inv.buyer_name✅Buyer's name.
inv.buyer_legal_name✅Buyer's organization name.
inv.buyer_taxBuyer's tax code.
inv.buyer_address✅Buyer's address.
inv.buyer_phone_numberNo (only MISA, FPT, Viettel)Buyer's phone number.
inv.buyer_emailBuyer's email. Example: '[email protected]'.
inv.buyer_id_numberNo (only 1Invoice, MISA)Buyer's personal identification number.
inv.buyer_bank_accountBuyer's bank account number.
inv.buyer_bank_nameName of the bank for the account number.
inv.payment_method✅Payment method (TM, CK, TM/CK, DTCN, KTT, TTD, HBT, TQL, L/C, TTR, TM/CK/BTCN).
inv.discountDiscount amount.
inv.sum_v✅Total before tax, after discount (converted to VND).
inv.sum_sale_v✅Total goods amount before tax, before discount (converted to VND).
inv.vat_vYes if it is a VAT invoiceTotal tax amount (converted to VND).
inv.total_v✅Total amount after tax (converted to VND).
inv.total_v_in_words✅Total amount after tax in words (VND).
inv.seqInvoice number.
inv.sid✅Order code by merchant. Must not be duplicated.
inv.sum✅Total before tax, after discount (original currency).
inv.sum_sale✅Total goods amount before tax, before discount (original currency).
inv.vatYes if it is a VAT invoiceTotal tax amount in original currency.
inv.total✅Total payment amount including tax in original currency.
inv.form✅Invoice template registered for use on the system.
inv.aunNo (only FPT)Determines which system manages invoice number issuance: enterprise self-manages numbering ('aun': 1, an invoice number is required in the 'seq' field); eInvoice automatically issues numbers ('aun': 2).
inv.signNo (only FPT)Used for return invoices ('sign': -1: marks a return invoice; 'sign': 1 or no field: a normal invoice).
inv.type_refNo (only FPT)Field that identifies the type of invoice in use (1: Invoice under TT78; empty: Invoice under TT32).
inv.stax✅Seller's tax code. Example: '2392190986'.
inv.typeYes (only FPT, Vietel)Invoice type. Example: '01GTKT'.
inv.is_send_mailWhether to send an email upon successful issuance.
inv.receiver_nameName of the email recipient.
inv.receiver_emailEmail recipient addresses, separated by ; (Only applies in Product).
inv.items[].line✅Line number of the goods item.
inv.items[].type✅Goods type (1: Normal, 2: Promotion, 3: Discount, 4: Note, 5: Special transport goods).
inv.items[].codeGoods code.
inv.items[].nameGoods name.
inv.items[].unitGoods unit.
inv.items[].quantityGoods quantity.
inv.items[].priceGoods unit price.
inv.items[].perdiscountDiscount percentage (%).
inv.items[].amtdiscountDiscount amount.
inv.items[].amountAmount for each line of goods/services.
inv.items[].amountnAmount after discount (= amount - amtdiscount).
inv.items[].vrtYes if it is a VAT invoiceTax rate type, the value depends on the provider ('0', '5', '10').
inv.items[].vatYes if it is a VAT invoiceVAT amount for each item.
inv.items[].totalTotal amount including VAT for each item.
inv.tax_rate_info[].vrtYes if it is a VAT invoice (only MISA, Viettel)Aggregated tax rate type: KCT(MISA) || -1 (Viettel): taxable; KKKNT (MISA) || -2 (Viettel): declared and paid; 0%: tax rate 0%; 5%: tax rate 5%; 8%: tax rate 8%; 10%: tax rate 10%; KHAC:x%: other tax rate type (Example: KHAC:3.5%).
inv.tax_rate_info[].amountnYes if it is a VAT invoice (only MISA, Viettel)Total amount before tax of goods lines grouped by tax rate.
inv.tax_rate_info[].vatYes if it is a VAT invoice (only MISA, Viettel)Total tax amount of the goods lines.

Notes by provider​

Differences in field values by provider for certain fields when creating an invoice​

Field name1InvoiceFPTMisaViettel
inv.serialRequiredOptionalRequiredRequired
inv.invoice_dateRequiredRequiredRequiredOptional
inv.staxPass the tax codePass the tax codePass the tax codePass an empty string ""
inv.payment_methodNot required to be "TM/CK", "CK"... it can be customized, for example "QR", "CARD"Must be "TM", "CK", "TM/CK"....Not required to be "TM/CK", "CK"... it can be customized, for example "QR", "CARD"Not required to be "TM/CK", "CK"... it can be customized, for example "QR", "CARD"
inv.form"1""1" (do not pass this field if serial has already been passed)""template_code returned from the invoice serial list
inv.typeOptionalRequiredOptionalRequired
inv.items[].type1 Goods nature:
- Goods/services (tchat value is 1)
- Promotion (tchat value is 2)
- Commercial discount (tchat value is 3)
- Note/description (tchat value is 4)		"" Goods form has 4 types:
- MT : Note, description
- CK : Commercial discount
- KM : Promotion
- Pass empty : Normal		1 Goods nature:
1: Normal goods
2: Promotion
3: Discount
4: Note/description
5: Special transport goods		"" - Null or 1- Goods (Generates line number, quantity and unit price are required)
- 2: Note (Does not generate a line number and does not add the amount to the total payment)
- 3: Discount (Does not generate a line number, quantity and unit price are not required, add isIncreaseItem = false to indicate an amount reduction)
- 4: Other fee (Does not generate a line number, quantity and unit price are not entered)
- 5: Promotion (Generates a line number, quantity and unit price are required)
- 6: Special goods; if passing special goods (ND 70), see the list of required fields below
inv.items[].vrt"8", "10" …
Pass the following fixed values:
10: Tax rate 10%
8: Tax rate 8%
5: Tax rate 5%
0: Tax rate 0%
-1: Not taxable
-2: Not declared and paid
If an additional tax rate outside the list arises, contact 1Invoice
Required if tchat is 1,2,3
Optional if tchat is 4		"8", "10" …
Tax rate type : ( 0, 5, 8, 10, -1, -2)
+ 0: tax rate 0%
+ 5: tax rate 5%
+ 8: tax rate 8%
+ 10: tax rate 10%
+ -1: Not taxable
+ -2: Not declared and paid
Other than the 6 tax rate types above: Other tax rate		"8%", "10%" …
KCT: taxable
KKKNT: declared and paid
0%: tax rate 0%
5%: tax rate 5%
8%: tax rate 8%
10%: tax rate 10%
KHAC:x%: other tax rate type (Example: KHAC:3.5%)		"8", "10" …
Tax rate of goods/services (-2: no tax, -1: not declared, 0: 0%, 5: 5%, 8: 8%, 10: 10%...).

Issuing an invoice for a retail customer​

Field1InvoiceFPTMisaViettel
Organization name (inv.buyer_legal_name)OptionalRequiredOptionalOptional
Address (inv.buyer_address)OptionalRequired
The content can be: "Customer does not take invoice"		OptionalOptional

Response​

NameDescription
data.search_codeCode for the user to look up the invoice
data.seqInvoice number
data.tax_authority_codeTax authority code
data.vpidId used to view the PDF or sign the invoice
data.error_codeError code if any (With an error code: creation failed; without an error code: creation successful)
data.transaction_idTransaction code if any

Notes on the returned result by provider​

Differences between the response data when creating an invoice (✅: yes, ❌: no)

Field1InvoiceFPTMisaViettel
Tax authority code
Lookup code
Invoice number
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
            }
        ]
    }
}'