> ## Documentation Index
> Fetch the complete documentation index at: https://hdsd.bitebolt.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tích hợp Hóa đơn điện tử (e-Invoice)

> Hướng dẫn tích hợp và xuất Hóa đơn điện tử trực tiếp từ Bitebolt POS cho các đối tác HILO, WINTECH, EasyInvoice, 1Invoice

Để tuân thủ quy định của cơ quan thuế về việc xuất hóa đơn điện tử khởi tạo từ máy tính tiền, Bitebolt POS cung cấp tính năng kết nối trực tiếp với các nhà cung cấp giải pháp Hóa đơn điện tử.

Hệ thống Bitebolt hiện đang hỗ trợ tích hợp sâu (API trực tiếp) với 4 nhà cung cấp Hóa đơn điện tử:

1. **HILO Invoice**
2. **WINTECH**
3. **EasyInvoice**
4. **1Invoice**

***

## 1. Hướng dẫn thiết lập trên POS Portal (Dành cho Quản lý)

Để hệ thống có thể xuất hóa đơn hợp lệ, quản lý cửa hàng cần thực hiện đấu nối tài khoản e-Invoice với Bitebolt. Tùy thuộc vào nhà cung cấp mà thông số cài đặt sẽ có chút khác biệt.

**Bước 1:** Đăng nhập vào POS Portal (Admin Portal).
**Bước 2:** Điều hướng đến mục **Cài đặt** (Settings) → **Hóa đơn điện tử** (e-Invoice).
**Bước 3:** Bật kích hoạt và chọn nhà cung cấp dịch vụ tương ứng.
**Bước 4:** Nhập các thông số cấu hình riêng của từng đối tác:

### A. Tích hợp HILO Invoice

* **Loại Hóa đơn (Type)**: Chọn `VAT` (Hóa đơn GTGT) hoặc `HKD` (Hộ kinh doanh).
* **Mã số thuế / Mã khách hàng (Code)**: Của doanh nghiệp đăng ký với HILO.
* **Tài khoản (Username) & Mật khẩu (Password)**: Thông tin tài khoản kết nối.
* **Host API**: Đường dẫn API do HILO cung cấp.
* **Ký hiệu hóa đơn (Pattern)**: Ký hiệu mẫu số/Ký hiệu hóa đơn.

### B. Tích hợp WINTECH

* **Loại Hóa đơn (Type)**: Chọn `VAT` hoặc `HKD`.
* **Client ID & Client Secret**: Cặp mã bảo mật kết nối API cấp bởi WINTECH.
* **Ký hiệu hóa đơn (Pattern)**.
* **Môi trường (Environment)**: Chọn `production` (Thực tế) hoặc `development` (Thử nghiệm).

### C. Tích hợp EasyInvoice

* **Loại Hóa đơn (Type)**: Chọn `VAT` hoặc `HKD`.
* **Mã số thuế (Enterprise Code)**.
* **Tài khoản (Username) & Mật khẩu (Password)**.
* **Ký hiệu mẫu số & Ký hiệu hóa đơn (Pattern)**.
* **Cấu hình mở rộng**: Invoice Code 01, Invoice Code 02.
* **Môi trường (Environment)**: `production` hoặc `development`.

### D. Tích hợp 1Invoice

* Nhập thông tin kết nối API xác thực tương ứng do AMIS cung cấp. (Bao gồm các thông số đăng nhập, API URL và Pattern mẫu số).

**Bước 5:** Tùy chỉnh chế độ phát hành: Bật tính năng **Tự động phát hành** (hóa đơn sẽ đẩy lên cơ quan thuế ngay khi chốt đơn) hoặc để chế độ **Thủ công** (quản lý tự duyệt và đẩy tay sau).
**Bước 6:** Nhấn **Lưu (Save)**.

***

## 2. Thao tác xuất hóa đơn điện tử trên ứng dụng POS

Khi khách hàng yêu cầu xuất hóa đơn VAT, thu ngân tại cửa hàng thực hiện thao tác như sau:

<Steps>
  <Step title="Mở form xuất hóa đơn">
    Tại màn hình thanh toán, trước khi bấm chốt thanh toán, nhấn vào biểu tượng/nút **Xuất hóa đơn điện tử (Issue e-Invoice)**.
  </Step>

  <Step title="Nhập thông tin xuất VAT">
    Một bảng nhập liệu sẽ xuất hiện. Thu ngân cần điền:

    * **Mã số thuế (Tax Code)**: Hệ thống Bitebolt hỗ trợ tự động tra cứu *Tên* và *Địa chỉ công ty* từ danh bạ doanh nghiệp quốc gia khi nhập MST hợp lệ.
    * **Tên công ty / Người mua hàng** (Company/Buyer Name).
    * **Địa chỉ công ty** (Address).
    * **Email nhận hóa đơn**: Nhập email của khách để hệ thống tự động gửi file hóa đơn PDF hoặc link tra cứu sau khi phát hành.
  </Step>

  <Step title="Lưu thông tin & Thanh toán">
    Nhấn **Xác nhận/Lưu thông tin VAT**. Sau đó chọn phương thức thanh toán và bấm **Xác nhận thanh toán** để đóng đơn như bình thường.
  </Step>

  <Step title="Hệ thống tự động xử lý">
    Ngay sau khi đơn hàng hoàn tất thanh toán, `tax-api` của Bitebolt sẽ xử lý phần thuế/phụ phí (Net amount) và tự động gọi API đẩy dữ liệu sang hệ thống của đối tác (HILO/WINTECH/EasyInvoice/1Invoice) để phát hành hóa đơn điện tử hợp lệ (nếu bật chế độ tự động).
  </Step>
</Steps>

<Info>
  Trạng thái phát hành hóa đơn điện tử của từng đơn hàng có thể được quản lý và đối soát tại tab **Lịch sử đơn hàng** trên POS Portal.
</Info>

***

## 3. Luồng xử lý nghiệp vụ Hóa đơn (Business Flow)

Để giúp bạn hiểu rõ hơn về cách hệ thống Bitebolt tương tác với các đối tác cung cấp dịch vụ Hóa đơn điện tử, dưới đây là chi tiết luồng xử lý (Flow) cho 2 nghiệp vụ chính: **Tạo mới hóa đơn (Create Invoice)** và **Thay thế hóa đơn (Replace Invoice)**.

### A. Luồng Tạo mới Hóa đơn (Create Invoice)

Nghiệp vụ này xảy ra khi một đơn hàng mới hoàn tất thanh toán và có yêu cầu xuất hóa đơn.

```mermaid theme={null}
sequenceDiagram
    participant POS as Bitebolt POS / Portal
    participant TaxAPI as Tax-API (Bitebolt)
    participant Provider as e-Invoice Provider (HILO/WINTECH...)

    POS->>TaxAPI: Gửi yêu cầu tạo hóa đơn (Order ID, Tax Info, Items)
    TaxAPI->>TaxAPI: Bóc tách trước thuế (Net), sau thuế (Gross)<br/>và loại bỏ Tip ra khỏi tính thuế
    TaxAPI->>Provider: Gọi API phát hành hóa đơn (Create/Issue Invoice)
    
    alt Thành công
        Provider-->>TaxAPI: Trả về kết quả (Invoice No, Pattern, PDF/Lookup Link)
        TaxAPI->>TaxAPI: Lưu trữ thông tin hóa đơn vào hệ thống
        TaxAPI-->>POS: Cập nhật trạng thái "Đã xuất hóa đơn"
    else Thất bại
        Provider-->>TaxAPI: Trả về mã lỗi (Sai thông tin, hệ thống bận...)
        TaxAPI-->>POS: Cảnh báo lỗi. Trạng thái "Lỗi xuất hóa đơn"
    end
```

### B. Luồng Thay thế Hóa đơn (Replace Invoice)

Nghiệp vụ này xảy ra khi hóa đơn đã xuất bị sai sót thông tin (tên công ty, địa chỉ, mã số thuế...) và khách hàng yêu cầu xuất lại hóa đơn mới thay thế cho hóa đơn cũ.

```mermaid theme={null}
sequenceDiagram
    participant POS as Bitebolt POS / Portal
    participant TaxAPI as Tax-API (Bitebolt)
    participant Provider as e-Invoice Provider (HILO/WINTECH...)

    POS->>TaxAPI: Gửi yêu cầu thay thế hóa đơn (Kèm thông tin mới & Lý do thay thế)
    TaxAPI->>TaxAPI: Kiểm tra tính hợp lệ của hóa đơn cũ
    TaxAPI->>Provider: Gọi API thay thế hóa đơn (Replace/Adjust)
    
    alt Thành công
        Provider-->>TaxAPI: Hủy/Thu hồi hóa đơn cũ & Cấp hóa đơn mới
        TaxAPI->>TaxAPI: Cập nhật CSDL (Đánh dấu hóa đơn cũ là Bị thay thế)
        TaxAPI-->>POS: Trả về link hóa đơn mới. Cập nhật trạng thái đơn hàng.
    else Thất bại
        Provider-->>TaxAPI: Báo lỗi (Ví dụ: Hóa đơn cũ đã kê khai thuế không thể thay thế)
        TaxAPI-->>POS: Hiển thị lỗi để quản lý xử lý thủ công
    end
```

<Warning>
  Việc **Thay thế hóa đơn** thường phải tuân thủ nghiêm ngặt các quy định của cơ quan thuế (như lập biên bản thỏa thuận thay thế). Quản lý cần đảm bảo đã thực hiện đầy đủ các thủ tục pháp lý đi kèm trước khi thao tác trên hệ thống.
</Warning>