npm package: @redonvn/invoice-purchase-sdk
Description: SDK TypeScript để tích hợp API hóa đơn đầu vào từ Matbao, dùng cho backend NestJS
Author: Redon
Latest version: 1.0.0

# @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

```bash
npm install @redon/invoice-purchase-sdk
```

## Sử dụng

### Khởi tạo client

```typescript
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

```typescript
const tokenResponse = await client.getToken({ 
  token: 'your-matbao-token' 
});

if (tokenResponse.Success) {
  const accessToken = tokenResponse.Data;
}
```

### Lấy danh sách hóa đơn

```typescript
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)

```typescript
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

```typescript
const detail = await client.getDetailByXml(accessToken, {
  data: 'base64EncodedXmlData',
  kiem_tra_hop_le: 1
});
```

### Lấy chi tiết hóa đơn từ URL

```typescript
const detail = await client.getDetailByUrl(accessToken, {
  url_xml: 'https://example.com/invoice.xml',
  kiem_tra_hop_le: 1
});
```

### Đăng nhập TCT

```typescript
// 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