– Ký số qua HSM/Esign nâng cao

– Không ký số (chỉ áp dụng cho hóa đơn từ MTT)

Product: https://api.meinvoice.vn/api/integration

    “success”:true/false,

    “errorCode”: “Mã lỗi”,

    “descriptionErrorCode”: “Mô tả lỗi”,

    “createInvoiceResult”: “Kết quả tạo hóa đơn”,

    “publishInvoiceResult”: “Kết quả phát hành hóa đơn”,

    “errors”: “Danh sách mô tả lỗi”,

    “data”: “Dữ liệu phản hồi”

    “customData”: “thông tin khác”

}

True: Thành công

False: Thất bại

Body của API

Response của API

để phục vụ việc hỗ trợ về sau nếu phát sinh

Nhận về app_id (dùng cho cả sandbox và product) và thông tin sandbox gồm

• Mã số thuế
• Tài khoản MeInvoice
• Mật khẩu MeInvoice

Khi thực hiện golive, lấy 3 thông tin trên từ bộ phận kế toán

Product: https://app3.meinvoice.vn/v3/ban-lam-viec

Xem thêm thiết lập hình thức hóa đơn sử dụng

– Xem hướng dẫn

Lưu ý:

– Token có hạn 14 ngày, chỉ nên gọi ở đầu phiên làm việc (lần đầu đăng nhập, đầu ngày, đầu tuần …)

Lưu ý: Chỉ thực hiện gọi lại khi Ký hiệu hóa đơn có sự thay đổi (không tính thay đổi năm ký hiệu)

– Xem mô tả phát hành dùng HSM/eSgin nâng cao

Lưu ý:

– Mẫu hóa đơn phải đang ở trạng thái Sử dụng

– Tờ khai phải đang ở trạng thái CQT chấp nhận

– Sử dụng SignType đúng với loại hình ký số mong muốn

1: Ký số qua USB/file mềm

2: Ký số qua HSM, có hiển thị CKS

3: Ký số qua HSM, có hiển thị CKS, luồng bất đồng bộ

4: Ký số sau loại Vé không mã, không hiển thị CKS

5: Ký số sau loại Hóa đơn MTT, không hiển thị CKS

6: Ký số sau loại Hóa đơn/Vé MTT, không hiển thị CKS, luồng bất đồng bộ

– Việc Round số chữ số thập phân phải khớp với số lượng được định nghĩa trong OptionUserDefined

– Khuyến nghị Round từng phần rồi cộng tổng thay vì cộng tổng xong Round

VD năm 2024, ký hiệu là 1C24MYY thì sang năm 2025, ký hiệu sẽ đổi thành 1C25MYY (hệ thống MISA tự động xử lý theo thông tin InvDate)

– Môi trường product: https://app3.meinvoice.vn

(Menu Báo cáo/Bảng kê hóa đơn đã sử dụng)

X = 1: hóa đơn GTGT

X = 2: hóa đơn bán hàng

X = 5: vé điện tử

X = 6: phiếu xuất kho

VD: 1C25TYY (hóa đơn GTGT)

X = C: hóa đơn có mã

X = K: hóa đơn không mã

VD: 1C25MYY (hóa đơn có mã)

X = T: hóa đơn thường

X = M: hóa đơn từ máy tính tiền

VD: 1C25MYY (hóa đơn từ máy tính tiền)

InvoiceNumberNotCotinuous

– Vòng lặp: [Gửi request => nhận response => xử lý response => lưu lại thông tin hóa đơn]

    “appid“: “{AppID}”,

    “taxcode“: “{taxcode}”,

    “username“: “{user meinvoice}”,

    “password“: “{pasword meinvoice}”

}

    “Success“: <false/true>,

    “Data“: “<Dữ liệu token trả về>“,

    “ErrorCode“: “<Trống hoặc Mã lỗi>”,

    “Errors“: “”,

    “CustomData“:””

}

invoiceWithCode: true/false (dùng loại hóa đơn có mã hay không mã)

ticket: true/false (lấy mẫu vé)

Authorization: Bearer {token}

    “Success“: <false/true>,

    “Data“: “<Danh sách mẫu>“,

    “ErrorCode“: “<Trống hoặc Mã lỗi>”,

    “Errors“: “”,

    “CustomData“:””

}

Lưu lại thông tin IsSendSummary, InvSeries của mẫu hóa đơn trong Data, để thực hiện khi phát hành hóa đơn

Authorization: Bearer {token}

      InvoiceData

}

Chỉ xem được 1 hóa đơn

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “errors“: [],

    “data“: “link xem hóa đơn“,

    “customData“: null

}

Authorization: Bearer {token}

    “SignType“: 1,

    “InvoiceData“: [list InvoiceData],

    “PublishInvoiceData“: null

}

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “createInvoiceResult“: [danh sách xml được tạo],

    “publishInvoiceResult“: null

}

Kiểm tra có createInvoiceResult.ErrorCode là chưa thành công

Dữ liệu XML của hóa đơn là thẻ: createInvoiceResult.InvoiceData

computerName: tên/ip của máy cài đặt tool ký số

    “PinCode“: “xxxxxxx”, //mật khẩu của cks

    “XmlContent“: {đối tượng XML được tạo ở bước 5.1}

}

    “Status“: 200,

    “PayLoad“: “”, //Chuỗi XML đã được ký số

    “Message“: null //thông báo lỗi nếu cố

}

Authorization: Bearer {token}

CompanyTaxCode: {taxcode}

    “SignType“: 1,

    “InvoiceData“: null

    “PublishInvoiceData“: [danh sách PublishInvoiceData]

}

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “createInvoiceResult“: null,

    “publishInvoiceResult“: [danh sách thông tin hóa đơn phát hành]

}

Kiểm tra có publishInvoiceResult.ErrorCode là chưa thành công

Authorization: Bearer {token}

    “SignType“: 2|5, (2: có hiển thị CKS; 5: Không hiển thị CKS)

    “InvoiceData“: [danh sách hóa đơn phát hành]

    “PublishInvoiceData“: null

}

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “createInvoiceResult“: null,

    “publishInvoiceResult“: [danh sách thông tin hóa đơn phát hành]

}

Kiểm tra có publishInvoiceResult.ErrorCode là chưa thành công

Kiểm tra publishInvoiceResult.ErrorCode, nếu empty thì hóa đơn mới được phát hành thành công

InvoiceNumberNotCotinuous)

Authorization: Bearer {token}

CompanyTaxCode: {taxcode}

VD: [“TranID1”, “TranID1”, …]

TranID1: Mã tra cứu hóa đơn

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “errors“: [],

    “data“: “link xem hóa đơn“,

    “customData“: null

}

Nếu muốn xem lâu dài có thể tải file pdf

invoiceCalcu: true/false là hóa đơn phát hành từ máy tính tiền

downloadDataType: xml/pdf/All

VD: [“TranID1”, “TranID1”, …]

TranID1: Mã tra cứu hóa đơn, tối đa 50 TransID/lần call

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “errors“: [],

    “data“: “InvoiceDataPublished“,

    “customData“: null

}

Mô tả InvoiceDataPublished

[

{

 “TransactionID“: “Mã tra cứu hóa đơn”,

 “Data“: “Dữ liệu của hóa đơn (dang base64)”,

}

]

    “SendEmailDatas“: 

      [

           {

         “TransactionID“: “Mã tra cứu”,

         “ReceiverName“: “Tên người nhận”,

         “ReceiverEmail“: “Email nhận hóa đơn”,

         “CCEmail“: “Email cc”,

“ReplyEmail“: “Email reply phản hồi”

           }

      ], //Danh sách gửi email của hóa đơn

      “IsInvoiceCode“: true/false, //(hóa đơn có mã/không mã)

      “IsInvoiceCalculatingMachine“: true/false //(hóa đơn MTT/thường)

}

Nếu gửi nhiều email, mỗi email cách nhau bởi dấu “;” (chấm phảy), chỉ gửi 1 loại hình hóa đơn/ loại hóa đơn trong 1 request

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “errors“: [],

    “data“: “”,

    “customData“: null

}

invoiceCalcu: true/false là hóa đơn phát hành từ máy tính tiền

inputType: 1

inputType = 1: lấy theo TransactionID

inputType = 2: lấy theo RefID

VD: [“TranID1”, “TranID1”, …]

TranID1: Mã tra cứu/RefID của hóa đơn, tối đa 50 mã/lần call

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “errors“: [],

    “data“: “List InvoiceStatus“,

    “customData“: null

}

invoiceCalcu: true/false là hóa đơn phát hành từ máy tính tiền

Converter: người chuyển đổi

ConvertDate: ngày chuyển đổi (định dạng yyyy-MM-dd)

VD: [“TranID1”, “TranID1”, …]

TranID1: Mã tra cứu/RefID của hóa đơn, tối đa 50 mã/lần call

    “success“: true,

    “errorCode“: null,

    “descriptionErrorCode“: null,

    “errors“: [],

    “data“: “dữ liệu hóa đơn chuyển đổi sang giấy dạng base64string“,

    “customData“: null

}

Một chuỗi gồm 12 ký tự dạng số, không validate theo cấu trúc chi tiết , Không bắt buộc

(Chỉ sử dụng ở ND70)

Cho phép nhập dạng chuỗi gồm 20 ký tự

(Chỉ sử dụng ở ND70)

(Chỉ sử dụng ở ND70)

=Sum(AmountOC, itemType = 1)  – 

Sum(AmountOC, itemType = 3)

= TotalSaleAmountOC * ExchangeRate

=Sum(DiscountAmountOC, itemType= 1) + Sum(AmountOC, itemType= 3)

= TotalDiscountAmountOC* ExchangeRate

= Sum(AmountWithoutVATOC, itemtype =1) –

Sum(AmountWithoutVATOC, itemtype =3)

= TotalAmountWithoutVATOC * ExchangRate

=Sum(VATAmountOC, itemType = 1) –

Sum(VATAmountOC, itemType =3)

=TotalVATAmountOC * ExchangRate

= TotalAmountWithoutVATOC +

TotalVATAmountOC

= TotalAmountOC * ExchangRate

1: thay thế

2: điều chỉnh

1: Hóa đơn NĐ 123

3: Hóa đơn NĐ 51

VD: ký hiệu của hóa đơn bị thay thế là 1C24MAA

thì OrgInvTemplateNo = 1 (ký hiệu đầu tiên)

VD: ký hiệu của hóa đơn bị thay thế là 1C24MAA

thì OrgInvSeries = C24MAA (bỏ ký hiệu đầu tiên)

1: Hàng hóa thường

2: Khuyến mại

3: Dòng hàng Chiết khấu thương mại

4: Ghi chú/diễn giải

5: Hàng hóa đặc thù vận tải

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%)

((AmountOC – DiscountAmountOC + ServiceAmountOC) * ExciseTaxRate)/100

((AmountOC – DiscountAmountOC) * ServiceFeeRate)/100

1: kinh doanh xe

2: dịch vụ vận chuyển

3: dịch vụ vận tải qua nền tảng số

SKhung, SMay: áp dụng TypicalItem = 1 (số khung, số máy)

BKSPTVChuyen: áp dụng TypicalItem = 2, 3 (biển kiểm soát của phương tiện)

KCT: không chịu thuế

KKKNT: không 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%)

=(Sum(AmountWithoutVATOC, itemtype =1)  – 

Sum(AmountWithoutVATOC, itemtype =3))

(Sum(VATAmountOC, itemType = 1) – 

Sum(VATAmountOC, itemType =3))

True: có

1: Đã phát hành

1: hóa đơn gốc

2: hóa đơn bị hủy

3: hóa đơn thay thế

5: hóa đơn điều chỉnh

7: hóa đơn bị thay thế

8: hóa đơn bị điều chỉnh

0: Gốc

1: Thay thế

2: Điều chỉnh

5: Chiết khấu thương mại

0: chưa gửi

1: gửi lỗi

2: thuế chấp nhận 

3: thuế từ chối

– Không thuộc loại được cho phép

– Giá trị bắt buộc – không được trống

– Vượt quá giới hạn MaxLength cho phép

0: Loại phiếu xuất kho

1: thông tin thiếu

– Không thuộc loại được cho phép

– Giá trị bắt buộc – không được trống

– Vượt quá giới hạn MaxLength cho phép

– có 2 TH mã lỗi này thường gặp:

– TH1: kỹ thuật đơn vị dùng vòng lặp for gửi request liên tục

=> Xử lý: Báo kỹ thuật xử lý mỗi khi phát hành xong 1 request thì sleep khoảng 3s

– TH2: có nhiều điểm máy trạm phát hành đồng thời

=> Xử lý: Tư vấn đơn vị mỗi 1 điểm máy trạm phát hành sẽ theo 1 ký hiệu khác nhau

– PA chung là: gặp mã lỗi này thì retry gọi lại hàm phát hành

=> Xử lý: trường hợp retry vẫn bị thì liên hệ kỹ thuật MISA