# Kết nối nhà cung cấp hoá đơn điện tử

Kết nối tài khoản hoá đơn điện tử Mắt Bão của bạn để Hạ Tầng xuất hoá đơn dưới mã số thuế của bạn, chọn mẫu và ký hiệu, và đồng bộ hai bên.

Hạ Tầng xuất hoá đơn điện tử **dưới mã số thuế của bạn, qua tài khoản của chính bạn** ở nhà cung cấp hoá đơn. Hoá đơn, dải số và việc ký số vẫn nằm ở nhà cung cấp bạn đang dùng và đã đăng ký với cơ quan thuế; Hạ Tầng tạo bản nháp, gửi đi ký và theo dõi từng hoá đơn. Hiện tại nhà cung cấp được hỗ trợ là **Mắt Bão**.

Kết nối nhà cung cấp cần quyền **Quản lý** trong module Thanh toán. Làm một lần cho mỗi môi trường: ở **Thử nghiệm** với sandbox demo của Mắt Bão, ở **Chính thức** với tài khoản thật.

## Trước khi bắt đầu

- Một **tài khoản hoá đơn điện tử Mắt Bão có quyền API**. Mã số thuế, tài khoản và mật khẩu API nằm trong mục **Cấu hình API** trên cổng hoá đơn Mắt Bão. Nếu không thấy mục này, hãy nhờ Mắt Bão bật quyền API.
- Ít nhất một **mẫu số và ký hiệu** đã đăng ký cho doanh nghiệp tại Mắt Bão.
- Ở môi trường thử nghiệm: thông tin đăng nhập một tài khoản demo Mắt Bão (cổng demo.matbao.in). Không có gì tạo ở đó được gửi tới cơ quan thuế.

## Kết nối

1. Mở **Thanh toán → Cài đặt thanh toán**, tab **Nhà cung cấp hoá đơn**.
2. Trong khung **Thêm nhà cung cấp**, chọn **Mắt Bão** ở ô **Nhà cung cấp**.
3. Nhập **Tax code (MST)**, **API user** và **API password**.
4. Bấm **Kiểm tra kết nối**. Hạ Tầng đăng nhập và đọc danh sách mẫu của tài khoản: biểu mẫu cho biết đã đăng nhập với mã số thuế nào và tìm thấy bao nhiêu mẫu.
5. Ở **Mẫu và ký hiệu**, chọn mẫu dùng để xuất hoá đơn. Danh sách cho biết mỗi mẫu còn bao nhiêu số hoá đơn.
6. Ở **Khi đơn đã thanh toán cần hoá đơn**, chọn:
   - **tạo nháp, tôi tự gửi duyệt**: Hạ Tầng dừng ở bản nháp, người trong đội kiểm tra rồi gửi duyệt, hoặc
   - **tạo nháp rồi gửi duyệt**: hoá đơn được ký tự động.
7. Tích **Nhập cả hoá đơn tạo trên trang nhà cung cấp** nếu bạn cũng xuất hoá đơn trực tiếp trên cổng Mắt Bão và muốn thấy chúng trong Hạ Tầng.
8. Bấm **Kiểm tra và kết nối**.

![Biểu mẫu kết nối tài khoản Mắt Bão ở môi trường thử nghiệm](https://hatang.dev/help/img/vi/payments/invoice-providers.webp)

Mật khẩu được lưu mã hoá và không bao giờ hiển thị lại.

## Gửi Callback URL cho Mắt Bão

Sau khi kết nối, thẻ nhà cung cấp hiện một **Callback URL**. Gửi địa chỉ này cho bộ phận hỗ trợ của Mắt Bão và nhờ họ cài cho tài khoản của bạn. Khi đó, mọi thay đổi ở phía Mắt Bão (ký số, mã của cơ quan thuế, huỷ, thay thế) về Hạ Tầng ngay lập tức. Nếu không cài, Hạ Tầng hỏi Mắt Bão mỗi phút một lần, vẫn chạy được nhưng chậm hơn; thẻ cho biết lần kiểm tra gần nhất.

## Quản lý kết nối

| Thao tác | Khi nào |
|---|---|
| **Đặt mặc định** | Khi có nhiều nhà cung cấp, hoá đơn mới dùng nhà cung cấp mặc định trừ khi bạn chọn khác |
| **Đổi thông tin đăng nhập** | Mắt Bão từ chối mật khẩu đã lưu, ví dụ sau khi bạn đổi mật khẩu trên cổng của họ. Cảnh báo cho biết hoá đơn đang tạm dừng; nhập thông tin hiện tại rồi bấm **Kiểm tra và lưu**. Các hoá đơn tạm dừng sẽ chạy tiếp sau đó |
| **Đồng bộ ngay** (ở trang **Hoá đơn điện tử**) | Muốn lấy thay đổi từ Mắt Bão ngay |
| **Gỡ liên kết** | Hạ Tầng ngừng tạo hoá đơn bằng tài khoản này. Hoá đơn đã phát hành vẫn còn trong Hạ Tầng và ở Mắt Bão. Nhà cung cấp tiếp theo trở thành mặc định |

## Hạ Tầng làm gì với nhà cung cấp

- **Tạo bản nháp** ở Mắt Bão từ thanh toán hoặc từ hoá đơn bạn tạo, gồm người mua, hàng hoá và VAT.
- **Gửi duyệt** (ký số), tự động hoặc khi bạn bấm, tuỳ chế độ đã chọn.
- **Đọc lại** kết quả: số hoá đơn và mã tra cứu, mã hoặc lời từ chối của cơ quan thuế, và thay đổi làm trên cổng Mắt Bão.
- **Tự thử lại** khi Mắt Bão chậm hoặc gián đoạn. **Thanh toán → Tình trạng tích hợp** cho biết lệnh gọi nào đang chờ hoặc lỗi.

Hạ Tầng không bao giờ huỷ hay xoá hoá đơn đã gửi tới cơ quan thuế; việc đó làm trên cổng Mắt Bão, hoặc bằng hoá đơn thay thế.

## Xử lý sự cố

| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| **Kiểm tra kết nối** thất bại | Sai mã số thuế, tài khoản hoặc mật khẩu, hoặc chưa bật quyền API | Chép lại từ **Cấu hình API**; nhờ Mắt Bão bật quyền API |
| Danh sách mẫu trống | Tài khoản chưa có mẫu đăng ký dùng qua API | Đăng ký mẫu số và ký hiệu tại Mắt Bão rồi kiểm tra lại |
| Hoá đơn dừng kèm cảnh báo thông tin đăng nhập | Mật khẩu đã đổi ở Mắt Bão | **Đổi thông tin đăng nhập** |
| Thay đổi trên cổng Mắt Bão về chậm | Chưa cài Callback URL | Gửi **Callback URL** cho hỗ trợ Mắt Bão |
| Hoá đơn của thanh toán đã trả **thất bại** với "No e-invoice provider is connected in this environment" | Nhà cung cấp được kết nối ở môi trường kia | Kết nối nhà cung cấp ở đúng môi trường của thanh toán |

Chi tiết API và trạng thái hoá đơn cho lập trình viên có trong [Hoá đơn điện tử ở trang dành cho lập trình viên](https://hatang.dev/vi/docs/guides/payments/einvoices).