npm package: @redonvn/mat-bao-ca-sdk
Description: TypeScript SDK for MatBao CA Digital Signature API
Author: MatBao CA SDK Team
Latest version: 1.0.0

# MatBao CA SDK

TypeScript SDK cho dịch vụ chữ ký số MatBao CA.

## Cài đặt

```bash
npm install @redonvn/mat-bao-ca-sdk
```

## Sử dụng

### Khởi tạo SDK

```typescript
import { MatBaoCASDK } from '@redonvn/mat-bao-ca-sdk';

const sdk = new MatBaoCASDK({
  baseUrl: 'https://demo-api-econtract-mbc.matbao.in', // hoặc production URL
  taxcode: '0302712571-999',
  username: 'demo@matbao.com',
  password: 'demo@123!'
});
```

### Xác thực

```typescript
try {
  const authResponse = await sdk.authenticate();
  if (authResponse.Success) {
    console.log('Xác thực thành công');
  }
} catch (error) {
  console.error('Lỗi xác thực:', error);
}
```

### Lấy thông tin chứng chỉ

```typescript
try {
  const certResponse = await sdk.getCertificate();
  if (certResponse.Success) {
    console.log('Certificate:', certResponse.Data);
  }
} catch (error) {
  console.error('Lỗi lấy certificate:', error);
}
```

### Ký file PDF

```typescript
const pdfSignRequest = {
  PdfBase64: 'base64_pdf_content',
  RecImgBase64: 'base64_signature_image',
  RecWidth: 200,
  RecHeight: 100,
  ArisingImgBase64: 'base64_hand_signature',
  ArisingImgWidth: 150,
  ArisingImgHeight: 75,
  ArisingPosition: 0 as const, // 0: Top; 1: Left; 2: Bottom; 3: Right
  ArisingPositionAlign: 1 as const, // 0: Left/Top; 1: Center/Middle
  Page: 1,
  X: 100,
  Y: 100,
  VerifiedByLabel: 'Xác thực bởi',
  SignedByLabel: 'Ký bởi',
  SignedDateLabel: 'Ngày ký',
  SignedDateFormat: 'dd/MM/yyyy HH:mm',
  AlignmentVerifiedByLabel: 'center' as const,
  AlignmentSignedByLabel: 'center' as const,
  AlignmentSignedDateLabel: 'center' as const,
  PositionSignedByLabel: 0 as const,
  PositionSignedDateLabel: 1 as const,
  PositionVerifiedByLabel: 2 as const,
};

try {
  const signResponse = await sdk.signPdf(pdfSignRequest);
  if (signResponse.Success) {
    console.log('PDF đã được ký thành công');
    // signResponse.Data chứa base64 của PDF đã ký
  }
} catch (error) {
  console.error('Lỗi ký PDF:', error);
}
```

### Ký dữ liệu XML

```typescript
const xmlSignRequest = {
  XmlDataBase64: 'base64_xml_content',
  SignatureLocation: 'signature_location_id',
  NodeToBeSigned: '//DSCKS/NBan'
};

try {
  const xmlSignResponse = await sdk.signXml(xmlSignRequest);
  if (xmlSignResponse.Success) {
    console.log('XML đã được ký thành công');
  }
} catch (error) {
  console.error('Lỗi ký XML:', error);
}
```

### Ký dữ liệu Hash

```typescript
const hashSignRequest = {
  Data: 'data_to_sign'
};

try {
  const hashSignResponse = await sdk.signHash(hashSignRequest);
  if (hashSignResponse.Success) {
    console.log('Hash đã được ký thành công');
  }
} catch (error) {
  console.error('Lỗi ký hash:', error);
}
```

### Tạo tài liệu từ template

```typescript
const createDocRequest = {
  TemplateID: 'template_id',
  Data: {
    // Dữ liệu tùy theo template
    customerName: 'Nguyễn Văn A',
    contractDate: '2024-01-01'
  }
};

try {
  const createResponse = await sdk.createDocument(createDocRequest);
  if (createResponse.Success) {
    console.log('Tài liệu đã được tạo thành công');
  }
} catch (error) {
  console.error('Lỗi tạo tài liệu:', error);
}
```

### Xem thông tin tài liệu

```typescript
const viewDocRequest = {
  DocumentID: 'document_id',
  DocumentCode: 'document_code',
  Type: 1 as const // 0: Không trả base64, 1: Có trả base64
};

try {
  const viewResponse = await sdk.viewDocument(viewDocRequest);
  if (viewResponse.Success) {
    console.log('Thông tin tài liệu:', viewResponse.Data);
  }
} catch (error) {
  console.error('Lỗi xem tài liệu:', error);
}
```

### Đăng ký dịch vụ

```typescript
const registerRequest = {
  HoTen: 'Nguyễn Văn A',
  ChucVu: 'Giám đốc',
  Khoa: 'Phòng kinh doanh',
  CMND: '123456789',
  NgayCap: '2020-01-01',
  LoaiGiayTo: 'CCCD',
  Email: 'example@email.com',
  DienThoai: '0123456789',
  GhiChu: 'Ghi chú',
  Files: [
    {
      file_name: 'cccd_mat_truoc.jpg',
      base64_file: 'base64_file_content'
    }
  ]
};

try {
  const registerResponse = await sdk.registerService(registerRequest);
  if (registerResponse.Success) {
    console.log('Đăng ký dịch vụ thành công');
  }
} catch (error) {
  console.error('Lỗi đăng ký dịch vụ:', error);
}
```

## API Reference

### Cấu hình

```typescript
interface MatBaoCAConfig {
  baseUrl: string;
  taxcode: string;
  username: string;
  password: string;
  timeout?: number; // mặc định 30000ms
}
```

### Phương thức chính

- `authenticate(authRequest?: Partial<AuthRequest>)`: Xác thực và lấy token
- `getCertificate()`: Lấy thông tin chứng chỉ
- `signPdf(request: PdfSignatureRequest)`: Ký file PDF
- `signXml(request: XmlSignatureRequest)`: Ký dữ liệu XML
- `signHash(request: HashSignatureRequest)`: Ký dữ liệu Hash
- `createDocument(request: CreateDocumentRequest)`: Tạo tài liệu từ template
- `createMultiDocument(request: CreateMultiDocumentRequest)`: Tạo nhiều tài liệu
- `viewDocument(request: ViewDocumentRequest)`: Xem thông tin tài liệu
- `signatureDocument(request: SignatureDocumentRequest)`: Ký tài liệu với chữ ký tay
- `uploadDocument(request: UploadDocumentRequest)`: Upload tài liệu có sẵn
- `updateStatus(request: UpdateStatusRequest)`: Cập nhật trạng thái tài liệu
- `registerService(request: RegisterServiceRequest)`: Đăng ký dịch vụ
- `isAuth()`: Kiểm tra trạng thái xác thực
- `logout()`: Đăng xuất

## Môi trường

### Demo
- URL: `https://demo-api-econtract-mbc.matbao.in`
- TaxCode: `0302712571-999`
- Username: `demo@matbao.com`
- Password: `demo@123!`

### Production
- URL: `https://api-econtract-mbc.matbao.in`

## License

MIT