@redon/invoice-purchase-sdk

SDK TypeScript để tích hợp API hóa đơn đầu vào từ Matbao, dùng cho backend NestJS với types rõ ràng.

Cài đặt

npm install @redon/invoice-purchase-sdk

Sử dụng

Khởi tạo client

import { InvoicePurchaseClient } from '@redon/invoice-purchase-sdk';

// Demo environment
const client = new InvoicePurchaseClient('https://demo-api-hoadondauvao.matbao.in');

// Production environment
// const client = new InvoicePurchaseClient('https://api-hoadondauvao.matbao.in');

Lấy access token

const tokenResponse = await client.getToken({ 
  token: 'your-matbao-token' 
});

if (tokenResponse.Success) {
  const accessToken = tokenResponse.Data;
}

Lấy danh sách hóa đơn

import { InvoiceStatus, DateSearchType } from '@redon/invoice-purchase-sdk';

const invoices = await client.loadData(accessToken, {
  fromDateYMD: '2025-01-01',
  toDateYMD: '2025-02-01',
  trangthai: InvoiceStatus.VALID,
  typeSearchDate: DateSearchType.SIGN_DATE,
  typeDataPDF: 0
});

if (invoices.Success) {
  for (const invoice of invoices.Data) {
    console.log('Số hóa đơn:', invoice.HDon?.DLHDon?.TTChung?.SHDon);
    console.log('Người bán:', invoice.HDon?.DLHDon?.NDHDon?.NBan?.Ten);
    console.log('Tổng tiền:', invoice.HDon?.DLHDon?.NDHDon?.TToan?.TgTTTBSo);
  }
}

Lấy danh sách hóa đơn từ TCT (v2)

import { InvoiceType } from '@redon/invoice-purchase-sdk';

const invoices = await client.loadDataTct(accessToken, {
  fromDateYMD: '2025-01-01',
  toDateYMD: '2025-02-01',
  loaihoadon: InvoiceType.WITH_CODE
});

Lấy chi tiết hóa đơn từ XML

const detail = await client.getDetailByXml(accessToken, {
  data: 'base64EncodedXmlData',
  kiem_tra_hop_le: 1
});

Lấy chi tiết hóa đơn từ URL

const detail = await client.getDetailByUrl(accessToken, {
  url_xml: 'https://example.com/invoice.xml',
  kiem_tra_hop_le: 1
});

Đăng nhập TCT

// 1. Lấy captcha
const captcha = await client.getCaptcha(accessToken);
const captchaKey = captcha.Data.key;
const captchaSvg = captcha.Data.content; // Render SVG để người dùng đọc

// 2. Đăng nhập với captcha
const loginResult = await client.loginTct(accessToken, {
  username: '0302712571', // Mã số thuế
  password: 'yourPassword',
  cvalue: 'K598HN', // Giá trị captcha người dùng nhập
  ckey: captchaKey
});

Types

SDK cung cấp đầy đủ TypeScript types:

Enums

• InvoiceStatus - Trạng thái hóa đơn (-1: tất cả, 0: hợp lệ, 1: không hợp lệ, 2: trùng)
• InvoiceType - Loại hóa đơn (-1: tất cả, 1: có mã, 2: không mã, 3: máy tính tiền)
• DateSearchType - Loại ngày tìm kiếm

Invoice Types

• InvoiceListItem - Item trong danh sách hóa đơn
• HDon - Hóa đơn đầy đủ
• TTChung - Thông tin chung
• NBan - Thông tin người bán
• NMua - Thông tin người mua
• HHDVu - Chi tiết hàng hóa/dịch vụ
• TToan - Thông tin thanh toán
• KTra - Kết quả kiểm tra hóa đơn

Request Types

• GetTokenRequest
• LoadDataRequest
• LoadDataTctRequest
• DetailByXmlRequest
• DetailByUrlRequest
• LoginTctRequest

Response Types

• ApiResponse<T> - Response chung
• CaptchaResponse
• InvoiceDetailResponse

Thông tin API

• Demo API: https://demo-api-hoadondauvao.matbao.in
• Production API: https://api-hoadondauvao.matbao.in
• Demo Portal: https://demo.matbao.in (username: demo, password: demo@123!)

License

MIT