Chuyển tới nội dung chính

Giới thiệu​

@invoice-sdk/api là thư viện SDK giúp tích hợp hệ thống quản lý hóa đơn điện tử nhanh và hiệu quả vào bất kỳ ứng dụng JavaScript/TypeScript nào (frontend hoặc backend).

SDK này đóng vai trò là lớp trung gian giao tiếp giữa client và hệ thống API hóa đơn. Mục tiêu là giúp developer:

  • Truy cập các chức năng hóa đơn bằng các hàm đơn giản, rõ ràng
  • Không cần viết lại logic gọi HTTP hoặc xử lý lỗi lặp lại
  • Tăng tốc thời gian tích hợp hệ thống hóa đơn vào sản phẩm

Cài đặt​

Để bắt đầu sử dụng Hub Invoice SDK, cài đặt gói @invoice-sdk/api vào dự án bằng một trong các package-manager phổ biến:

npm install @invoice-sdk/api

Khởi tạo SDK​

Khởi tạo và cấu hình apiInstance từ Invoice SDK. apiInstance này là cầu nối để tương tác với các endpoint của API.

import { InvoiceApi, Configuration } from '@invoice-sdk/api'

const configuration = new Configuration();
const apiInstance = new InvoiceApi(configuration);

Sử dụng Kiểu dữ liệu (Data Type) trong SDK Invoice​

Khi làm việc với SDK Invoice, việc hiểu và sử dụng các kiểu dữ liệu (Data Type) là rất quan trọng để đảm bảo truyền đúng định dạng dữ liệu và nhận được kết quả như mong muốn từ các hàm hoặc phương thức API.

1. Import kiểu dữ liệu​

Để sử dụng một kiểu dữ liệu được định nghĩa trong SDK, bạn cần import nó từ gói thư viện.

Ví dụ:
SDK Invoice có một kiểu dữ liệu tên là CreateInvoiceRequest để định nghĩa cấu trúc chi tiết của một hóa đơn. Import nó như sau:

import { CreateInvoiceRequest } from '@invoice-sdk/api';
ghi chú

Đối với các nhà cung cấp hóa đơn điện tử Provider khác nhau, sẽ cần sử dụng reqData khác nhau để phù hợp với Provider đó.

2. Định dạng biến với kiểu dữ liệu​

Sau khi đã import kiểu dữ liệu, có thể sử dụng nó để định nghĩa rõ ràng kiểu của một biến. Điều này giúp:

  • Biết được các thuộc tính (key) nào có sẵn trong biến đó.
  • Biết được kiểu dữ liệu của từng thuộc tính.
  • Nhận được sự hỗ trợ từ IDE với tính năng tự động gợi ý (autocompletion) và kiểm tra lỗi (type checking) ngay trong quá trình phát triển.

Ví dụ:
Có một biến myInvoice và biến này sẽ chứa thông tin chi tiết về một hóa đơn, theo định dạng của CreateInvoiceRequest. Có thể khai báo nó như sau:

const myInvoice: CreateInvoiceRequest = {
  invoiceId: "INV-2025-001",
  customerName: "Công ty ABC",
  totalAmount: 1000000,
  // ... các thuộc tính khác của CreateInvoiceRequest
};