MatBao CA SDK

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

Cài đặt

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

Sử dụng

Khởi tạo SDK

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: '[email protected]',
  password: 'demo@123!'
});

Xác thực

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ỉ

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

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

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

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

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

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ụ

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: '[email protected]',
  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

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: [email protected]
• Password: demo@123!

Production

• URL: https://api-econtract-mbc.matbao.in

License

MIT