Tài liệu API Hóa đơn điện tử Matbao-Invoice

Môi trường Hệ thống (Base URL)

Hệ thống cung cấp hai môi trường hoạt động biệt lập phục vụ kiểm thử và phát hành thực tế.

1. Đăng nhập hệ thống (api/auth/login)

Tham số dữ liệu Request Body

{
  // Request Body
  "MST": "string",
  "TDNhap": "string",
  "MKhau": "string"
}

// Response Body
{
  "Success": true,
  "Data": "<Dữ liệu api trả về / Chuỗi AccessToken>",
  "ErrorCode": "<Trống hoặc Mã lỗi>",
  "Message": "<Thông báo thành công hoặc thất bại>"
}

2.a. Danh sách mẫu hóa đơn (api/invoice/templates)

Thông tin trường dữ liệu

2.b. Tạo mới hóa đơn (api/invoice/create-invoice)

Bảng định nghĩa dữ liệu chi tiết khối Header

Thông tin Hàng hóa Dịch vụ lồng nhau (DSHHDVu)

2.c. Xóa bỏ hóa đơn (api/invoice/cancel-invoice)

MaSoHDon: Mã số hóa đơn (INVID mã hóa), độ dài 50 ký tự, Bắt buộc.

2.d. Tạo thông báo hóa đơn sai sót mẫu 04 (api/invoice/create-template-04)

Sử dụng khi cần khai báo thông tin giải trình mẫu 04 gửi Tổng cục thuế đối với danh sách hóa đơn lỗi hệ thống nội bộ.

2.e. Tải file XML và PDF của hóa đơn (api/invoice/download-invoice)

Yêu cầu bắt buộc các tham số: MaTraCuu (Chuỗi 100) và MaSoHDon (Chuỗi 50).

2.f. Lấy danh sách chi tiết hóa đơn (api/invoice/invoice-detail)

Tra cứu dải danh sách dựa theo khoảng thời gian TNLap và DNLap (Định dạng bắt buộc: yyyy-MM-dd).

2.g. Ký hóa đơn nháp (api/invoice/sign-invoice)

URL: POST <BaseUrl>/api/invoice/sign-invoice

Tham số đầu vào: MaSoHDon (Chuỗi 50, Bắt buộc).

2.h. Lấy XML hóa đơn chưa ký (api/invoice/get-xml-not-sign)

URL: GET <BaseUrl>/api/invoice/get-xml-not-sign?MaSoHDon=<MaSoHDon>

Trả về cấu trúc chuỗi XML thô mã hóa dưới định dạng Base64 phục vụ ký số bên thứ ba.

2.i. Ký XML (api/invoice/sign-xml)

URL: POST <BaseUrl>/api/invoice/sign-xml

Tham số cấu thành yêu cầu: XmlMaHoa64, MaVungKy, và đường dẫn chứng thư số DuongDanChuKy.

2.k. Xóa hóa đơn nháp (api/invoice/delete-invoice)

URL: POST <BaseUrl>/api/invoice/delete-invoice

Truyền khóa định danh MaSoHDon để gỡ bỏ hoàn toàn hóa đơn nháp chưa ký số khỏi database.

2.j. JSON hóa đơn trả về từ Webhook (Callback cấu hình)

Cấu trúc phản hồi thời gian thực từ cổng core Mắt Bão về webhook callback endpoint đối tác.

{
  "InvID": "QVh5dWZsYksyS0pyY...", // Mã số hóa đơn mã hóa INVID
  "No": 36245, // Số hóa đơn chính thức
  "Pattern": "1", // Mẫu số hóa đơn
  "Serial": "C25TAT", // Ký hiệu series dải hóa đơn
  "SO": "BH250024422", // Mã tham chiếu nội bộ hệ thống đối tác
  "Fkey": "7B164DE80848001", // Mã tra cứu hóa đơn trực tuyến
  "ArisingDate": "2025-05-16T00:00:00",
  "MCCQT": "007865BA205F284530AA353E42B75820B9", // Mã xác thực Cơ quan Thuế cấp
  "MaTTHDon": 4, // 1: Nháp | 2: Lỗi ký | 3: Chưa gửi CQT | 4: Đã cấp mã / tiếp nhận thành công
  "TenTTHDon": "Đã cấp mã / tiếp nhận"
}

3.a. Lấy danh sách tờ khai 01 (api/tokhai01/get-tokhai01)

URL: GET <BaseUrl>/api/tokhai01/get-tokhai01

Tham số lọc: TrangThai (0: Chưa ký, 1: Đã ký, 2: Đã gửi, 3: CQT đã duyệt).

3.b. Tạo mới tờ khai 01 (api/tokhai01/create-tokhai01)

URL: POST <BaseUrl>/api/tokhai01/create-tokhai01

Khởi tạo luồng thông tin đăng ký mới sử dụng hình thức hóa đơn điện tử hoặc chứng từ khấu trừ thuế TNCN lên hệ thống Tổng cục.

Phụ lục 1: Định nghĩa danh mục bảng Mã lỗi Hệ thống

Phụ lục 2: Danh mục ký hiệu mẫu số hóa đơn, chứng từ

Phụ lục 3: Quy tắc thiết lập cấu trúc Ký hiệu dải series Hóa đơn

Cấu trúc chuỗi series bao gồm tổ hợp chuẩn quy định gồm 6 ký tự viết liền không dấu:

• Ký tự 1: C (Có mã của Cơ quan Thuế) hoặc K (Không có mã).
• Ký tự 2-3: Hai số cuối của năm dương lịch lập hóa đơn (Ví dụ lập năm 2026 ghi là 26).
• Ký tự 4: Phân loại hóa đơn sử dụng (T: Doanh nghiệp đăng ký; M: Khởi tạo từ máy tính tiền; N: Phiếu xuất kho kiêm vận chuyển nội bộ; B: Phiếu gửi đại lý...).
• Ký tự 5-6: Do người bán tự xác định quản lý dải mẫu nội bộ (Mặc định nếu không phân loại dùng YY).