@redonvn/matbao-invoice-sdk

SDK chính thức cho Matbao Invoice API - Hóa đơn điện tử Mắt Bão, được xây dựng cho NestJS.

Cài đặt

npm install @redonvn/matbao-invoice-sdk

Thiết lập

Đăng ký Module

Sử dụng với static configuration

import { Module } from '@nestjs/common';
import { MatbaoInvoiceModule } from '@redonvn/matbao-invoice-sdk';

@Module({
  imports: [
    MatbaoInvoiceModule.register({
      baseUrl: 'https://demo-api-hddt.matbao.in:11443', // hoặc production URL
      mst: '0302712571-999',
      username: 'admin',
      password: 'your-password',
      timeout: 30000, // optional
    }),
  ],
})
export class AppModule {}

Sử dụng với async configuration

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { MatbaoInvoiceModule } from '@redonvn/matbao-invoice-sdk';

@Module({
  imports: [
    MatbaoInvoiceModule.registerAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService) => ({
        baseUrl: configService.get('MATBAO_BASE_URL'),
        mst: configService.get('MATBAO_MST'),
        username: configService.get('MATBAO_USERNAME'),
        password: configService.get('MATBAO_PASSWORD'),
      }),
    }),
  ],
})
export class AppModule {}

Cấu hình Environment Variables

# .env file
MATBAO_BASE_URL=https://demo-api-hddt.matbao.in:11443
MATBAO_MST=0302712571-999
MATBAO_USERNAME=admin
MATBAO_PASSWORD=your-password

Sử dụng

Inject Service vào Module của bạn

import { Injectable } from '@nestjs/common';
import { MATBAO_INVOICE_SERVICE_TOKEN, IMatbaoInvoiceService } from '@redonvn/matbao-invoice-sdk';

@Injectable()
export class InvoiceService {
  constructor(
    @Inject(MATBAO_INVOICE_SERVICE_TOKEN)
    private readonly matbaoInvoiceService: IMatbaoInvoiceService,
  ) {}
}

Các API Methods

1. Lấy danh sách mẫu hóa đơn

const templates = await this.matbaoInvoiceService.getTemplates(2024);
if (templates.Success) {
  console.log('Templates:', templates.Data);
}

2. Tạo mới hóa đơn

const invoiceData = [
  {
    KHMSHDon: '1',
    KHHDon: '24T',
    NLap: new Date().toISOString(),
    DVTTe: '704',
    TGia: 1,
    HTTToan: 'TM/CK',
    MaTraCuu: 'REF123',
    MTChieu: 'REF123',
    GChu: 'Ghi chú hóa đơn',
    TCHDon: 0, // Hóa đơn mới
    NMua_Ten: 'Công ty ABC',
    NMua_MST: '0100000000',
    NMua_DChi: 'Hà Nội',
    NMua_SDThoai: '0901234567',
    NMua_DCTDTu: '[email protected]',
    DSHHDVu: [
      {
        TChat: 1,
        STT: 1,
        MHHDVu: 'SP001',
        THHDVu: 'Sản phẩm A',
        DVTinh: 'Cái',
        SLuong: 10,
        DGia: 100000,
        ThTienChuaCK: 1000000,
        TLCKhau: 0,
        STCKhau: 0,
        ThTien: 1000000,
        TSuat: 10,
        TThue: 100000,
        TgTien: 1100000,
      },
    ],
    TgThTien: 1000000,
    TgTThue: 100000,
    TTCKTMai: 0,
    TGTKhac: 0,
    TgTTTBSo: 1100000,
    TgTTTBChu: 'Một triệu một trăm nghìn đồng',
    LoaiHDon: 1, // 1: Tạo hóa đơn và phát hành
  },
];

const result = await this.matbaoInvoiceService.createInvoice(invoiceData);
if (result.Success) {
  console.log('Invoice created:', result.Data);
}

3. Xóa bỏ hóa đơn

const result = await this.matbaoInvoiceService.cancelInvoice({
  MaSoHDon: 'invoice-id-here',
});

4. Tạo thông báo hóa đơn sai sót (Mẫu 04)

const result = await this.matbaoInvoiceService.createTemplate04({
  Loai: 1,
  So: 'TB001',
  NTBCCQT: new Date().toISOString(),
  DSHDon: [
    {
      STT: 1,
      MaSoHDon: 'invoice-id',
      KHMSHDon: '1',
      KHHDon: '24T',
      SHDon: '0000001',
      LADHDDT: 1,
      TCTBao: 1,
      LDo: 'Lý do điều chỉnh',
    },
  ],
});

5. Tải file XML và PDF của hóa đơn

const result = await this.matbaoInvoiceService.downloadInvoice({
  MaTraCuu: 'REF123',
  MaSoHDon: 'invoice-id',
});

6. Lấy danh sách chi tiết hóa đơn

const result = await this.matbaoInvoiceService.getInvoiceDetail({
  TNLap: '2024-01-01',
  DNLap: '2024-12-31',
  LoaiHDon: 2, // Hóa đơn mới
  TThaiHDon: 4, // Đã cấp mã/tiếp nhận
});

7. Ký hóa đơn nháp

const result = await this.matbaoInvoiceService.signInvoice({
  MaSoHDon: 'invoice-id',
});

8. Lấy XML hóa đơn chưa ký

const result = await this.matbaoInvoiceService.getXmlNotSign('invoice-id');

9. Ký XML

const result = await this.matbaoInvoiceService.signXml({
  XmlMaHoa64: 'base64-encoded-xml',
  MaVungKy: 'SigningData',
  DuongDanChuKy: 'HDon/DSCKS/NBan',
});

10. Xóa hóa đơn nháp

const result = await this.matbaoInvoiceService.deleteInvoice('invoice-id');

Constants

SDK cung cấp các enum constants để dễ dàng sử dụng:

import {
  InvoiceType,
  InvoiceNature,
  InvoiceStatus,
  InvoiceListType,
  ItemType,
  TaxRate,
  WebhookCallbackType,
} from '@redonvn/matbao-invoice-sdk';

// Invoice Type
InvoiceType.DRAFT = 0;  // Tạo hóa đơn nháp
InvoiceType.PUBLISH = 1; // Tạo hóa đơn và phát hành

// Invoice Nature
InvoiceNature.NEW = 0;             // Hóa đơn mới
InvoiceNature.REPLACE = 1;         // Thay thế
InvoiceNature.ADJUST_INCREASE = 2; // Điều chỉnh tăng

// Invoice Status
InvoiceStatus.DRAFT = 1;                // Nháp
InvoiceStatus.SIGN_ERROR = 2;           // Lỗi ký
InvoiceStatus.NOT_SENT_TO_CQT = 3;      // Chưa gửi CQT
InvoiceStatus.ISSUED = 4;               // Đã cấp mã/tiếp nhận

// Tax Rate
TaxRate.NOT_TAX = -2; // Không chịu thuế (KKKNT)
TaxRate.NOT_TAX_SHORT = -1; // Không chịu thuế (KCT)
TaxRate.ZERO = 0;   // 0%
TaxRate.FIVE = 5;   // 5%
TaxRate.EIGHT = 8;  // 8%
TaxRate.TEN = 10;   // 10%

Webhook Handler

Xử lý webhook từ Matbao Invoice:

import { Controller, Post, Body } from '@nestjs/common';
import { InvoiceWebhookData } from '@redonvn/matbao-invoice-sdk';

@Controller('webhook')
export class WebhookController {
  @Post('matbao-invoice')
  async handleWebhook(@Body() webhookData: InvoiceWebhookData) {
    console.log('Webhook received:', webhookData);

    // webhookData.Loai: 1=Tạo nháp, 2=Ký, 3=CQT phản hồi, 4=Xóa nháp
    // webhookData.MaTTHDon: Trạng thái hóa đơn
    // webhookData.TenTTHDon: Tên trạng thái
    // webhookData.InvID: Mã số hóa đơn

    return { received: true };
  }
}

Môi trường

Demo Environment

• URL: https://demo-api-hddt.matbao.in:11443
• Tài khoản demo: Vui lòng liên hệ Matbao

Production Environment

• URL: https://api-hddt.matbao.in:11443
• Tài khoản: Lấy từ trang quản lý hóa đơn Matbao

Xử lý lỗi

SDK sẽ throw exception khi có lỗi xảy ra:

try {
  const result = await this.matbaoInvoiceService.createInvoice(invoiceData);
} catch (error) {
  console.error('Invoice creation failed:', error.message);
  // Error format: "Matbao Invoice API Error: {Message} (Code: {ErrorCode})"
}

License

MIT

Hỗ trợ

• Tài liệu API: Liên hệ Matbao
• Issues: GitHub Repository