# TÀI LIỆU TÍCH HỢP 1INVOICE HUB

Đặc tả API kết nối tới **1Invoice Hub** — gateway hóa đơn điện tử đứng trước nhiều nhà cung cấp (1Invoice, FPT, MISA, Viettel). Tài liệu dùng trực tiếp cho developer và AI agent để tích hợp end-to-end.

# Hướng dẫn nhanh cho AI Agent (Integration flow)

- **URL pattern:** `<base_url>/<provider>/<endpoint>` — `provider` ∈ `1Invoice`, `one-invoice`, `fpt`, `misa`, `viettel`. Một số endpoint (ví dụ `declaration-status`) gọi trực tiếp `<base_url>/core-api/...` với `provider` là query param.
- **Header bắt buộc cho mọi call:** `X-Tax-Code: <MST người bán>`, `Content-Type: application/json`, và `Authorization: Bearer <token>` (trừ `sign-in`).
- **Luồng phát hành hóa đơn (end-to-end):**
  1. `POST /sign-in` → lấy `token` (nên cache ~50 phút; gọi lại khi hết hạn).
  2. `POST /create-invoice` → tạo hóa đơn. Nếu response báo token hết hạn (`error_code`/`message` chứa `TokenExpired`) → đăng nhập lại và thử lại đúng 1 lần.
  3. (Tùy chọn) `POST /sign-contract` → ký phát hành gửi Cơ quan Thuế (chỉ khi cần ký tự động).
  4. `GET /view-print-invoice` → xem/tải PDF (cần header auth → nên proxy/cache phía server).
  5. `GET /get-invoices`, `GET /get-invoice`, `GET /get-invoice-serials`, `GET /core-api/customers/declaration-status` → tra cứu, đối soát, lấy ký hiệu, kiểm tra trạng thái tờ khai.
- **Idempotency:** mỗi hóa đơn dùng `inv.sid` duy nhất (ví dụ `{MST}-{mã đơn}-{timestamp}`). Trùng `sid` → lỗi `88` / `DuplicateInvoiceRefID` (đổi `sid` rồi gọi lại).
- **Lưu ý triển khai:** chỉ phát hành cho đơn đã thanh toán; nếu bước ký tự động lỗi thì không nên chặn nghiệp vụ (có thể ký lại sau); tham chiếu mục **PHỤ LỤC** cho bảng trạng thái hóa đơn/CQT và các mã lỗi thường gặp.

# 1. Giới thiệu

Tài liệu này dành cho các nhà phát triển muốn kết nối ứng dụng (Client) tới các nhà cung cấp hóa đơn điện tử.

Mô hình Hub cho phép nền tảng thương mại (Merchant Platform) tích hợp **tập trung** với nhiều nhà cung cấp hóa đơn điện tử qua một gateway duy nhất — **1Invoice Hub** — giúp giảm chi phí và đơn giản hóa việc tích hợp riêng lẻ với từng nhà cung cấp.

Đây là **giải pháp Open API Hóa đơn điện tử của TConnect** — cùng hệ sinh thái với Open API thanh toán của TConnect — cung cấp cho đối tác một bộ API chuẩn hóa để phát hành và quản lý hóa đơn điện tử. Đối tác chỉ cần tích hợp **một lần** với TConnect (qua 1Invoice Hub) là có thể phát hành hóa đơn qua nhiều nhà cung cấp (1Invoice, FPT, MISA, Viettel).

## 1.1. Đường dẫn của API kết nối

Môi trường Staging: [https://stag-invoice-hub.1invoice.vn](https://stag-invoice-hub.1invoice.vn)

Môi trường Production: [https://invoice-hub.1invoice.vn](https://invoice-hub.1invoice.vn)

Lưu ý: Chỉ thực hiện test trên môi trường Staging, không test trên môi trường Production.

## 1.2. Danh sách các API của Nhà cung cấp đang được tích hợp trên 1Invoice Hub

| STT | Danh sách API | 1Invoice | 1Invoice (one-invoice) | FPT (fpt) | MISA (misa) | Viettel (viettel) |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | Lấy thông tin mã số thuế | API này không cần chỉ định nhà cung cấp |
| 2 | Đăng nhập lấy token | ✅ | ✅ | ✅ | ✅ | ✅ |
| 3 | Tạo hóa đơn | ✅ | ✅ | ✅ | ✅ (Ký tự động) | ✅ |
| 4 | Ký hóa đơn | ✅ | ✅ | ✅ | ❌ | ✅ |
| 5 | Lấy danh sách hóa đơn | ✅ | ✅ | ✅ | ❌ | ✅ |
| 6 | Lấy thông tin chi tiết hóa đơn | ✅ | ✅ | ✅ | ❌ | ✅ |
| 7 | Xem hóa đơn dạng file PDF | ✅ | ✅ | ✅ | ✅ | ✅ |
| 8 | Lấy danh sách ký hiệu hóa đơn | ✅ | ✅ | ✅ | ✅ | ✅ |
| 9 | Lấy danh sách tờ khai | ✅ | ✅ | ❌ | ❌ | ❌ |

## 1.3. Các quy ước chung

Khi gọi một API vào 1Invoice Hub, cần chỉ định rõ nhà cung cấp muốn sử dụng, cấu trúc URL một request được quy định như sau: <base_url> / <provider> /<endpoint>

Đối với request body, quy ước đặt tên field trong docs như sau:

a. x: field x của object a

a. n[]: field n là một mảng trong object a

a. n[]. x: field x trong mỗi phần tử của mảng n

a [n]: phần tử thứ n+1 của object a

a [n]. x: field x trong phần tử thứ n+1 của object a

# 2. Danh sách các hàm API

## 2.1. Lấy thông tin mã số thuế

Mục đích: Truy xuất thông tin chi tiết của mã số thuế (MST) dựa trên giá trị MST nhập vào.

- **Endpoint:** /tax-code

- **Method:** GET

Param:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| tax | string | Mã số thuế |

Response:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| ma_so_thue | string | Mã số thuế của doanh nghiệp. |
| masothue_id | string | ID mã số thuế |
| ten_cty | string | Tên đầy đủ của công ty/doanh nghiệp. |
| dia_chi | string | Địa chỉ đăng ký kinh doanh của doanh nghiệp. |
| cqthuecap_tinh | string / null | Cơ quan thuế cấp tỉnh quản lý (null nếu không có thông tin). |
| cqthue_ql | string | Cơ quan thuế quản lý trực tiếp. |
| nguoi_dai_dien | string | Họ và tên người đại diện pháp luật của công ty. |
| ngay_thanh_lap | Date (YYYY-MM-DD) | Ngày thành lập doanh nghiệp theo định dạng năm-tháng-ngày. |
| tthai | string / null | Mã trạng thái hoạt động của doanh nghiệp (null nếu không có thông tin) |
| ten_tthai | string / null | Tên mô tả trạng thái hoạt động của doanh nghiệp (null nếu không có thông tin). |

Sample:

```json
{
  "ma_so_thue": "0316887099",
  "masothue_id": "0316887099",
  "ten_cty": "CÔNG TY CỔ PHẦN GIẢI PHÁP ATOM",
  "dia_chi": "Phòng 802,Lầu 8, tòa nhà Vietnam Business Center, 57-59 Hồ T, Phường Sài Gòn, Thành phố Hồ Chí Minh, Việt Nam",
  "cqthuecap_tinh": "Chi cục thuế Hồ Chí Minh",
  "cqthue_ql": "Tân Định - Thuế cơ sở 1 Thành phố Hồ Chí Minh",
  "nguoi_dai_dien": "Trần Nguyễn Ngọc Trân",
  "ngay_thanh_lap": "2021-05-31",
  "tthai": null,
  "ten_tthai": null
}
```

Curl sample:

```bash
curl --location ' https://stag-invoice-hub.1invoice.vn/tax-code?tax=0316887099 '
```

## 2.2. Đăng nhập lấy token

Mục đích: Đăng nhập vào hệ thống của nhà cung cấp để lấy token.

- **Endpoint:** /sign-in

- **Method:** POST

Header:

- **Content-Type:** application/json

X-Tax-Code: [Mã số thuế người bán (cửa hàng…)]

Body:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| username | string | Tên đăng nhập |
| password | string | Mật khẩu |

Response

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| success | boolean | API thực thi thành công hay không |
| token | string | Thông tin token truy cập vào hệ thống |
| message | string | Thông báo tổng quan (nếu có) |
| error_code | string | Mã lỗi (nếu có) |
| errors | array[object] | Danh sách lỗi (nếu có) |

Sample:

```json
{
  "token": "O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=",
  "message": "Thành công",
  "success": true
}
```

Curl sample:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/sign-in' \ --header 'x-tax-code: 0106026495-998' \ --header 'Content-Type: application/json' \ --data-raw '{"username":"ATOM","password":"Kythuat@123"}'
```

## 2.3. Tạo hóa đơn

Mục đích: Tạo hóa đơn

- **Endpoint:** /create-invoice

- **Method:** POST

Header:

- **Authorization:** Bearer <token từ API đăng nhập>

- **Content-Type:** application/json

X-Tax-Code: [Mã số thuế người bán (cửa hàng…)]

Body:

| STT | Tên trường | Bắt buộc | Kiểu dữ liệu | Mô tả | Ví dụ |
| --- | --- | --- | --- | --- | --- |
| 1 | lang | Không | string | Ngôn ngữ hệ thống thông báo lỗi, mặc định là tiếng Việt | “en”, “vi” |
| 2 | inv.serial | Có | string | Ký hiệu hóa đơn (xem lưu ý bên dưới) | “1CM25MTS” |
| 3 | inv.invoice_date | Có | Date \| timestamp | Ngày phát hành hóa đơn (xem lưu ý bên dưới) | “2025-08-12T05:06:13” |
| 4 | inv.currency | Có | string | Đơn vị tiền tệ | "VND", "USD" |
| 5 | inv.ex_rate | Có | number | Tỷ giá | 1 |
| 6 | inv.buyer_name | Có | string | Tên người mua | “Nguyễn Văn A” |
| 7 | inv.buyer_legal_name | Có | string | Tên đơn vị mua | “Công ty ABC” |
| 8 | inv.buyer_tax | Không | string | Mã số thuế người mua | “09876543219” |
| 9 | inv.buyer_address | Có | string | Địa chỉ người mua | “123 Đường 04” |
| 10 | inv.buyer_phone_number | Không (only MISA, FPT, Viettel) | string | Số điện thoại người mua |  |
| 11 | inv.buyer_email | Không | string | Email người mua | “abc@gmail.com” |
| 12 | inv.buyer_id_number | Không (only 1Invoice, MISA) | string | Số định danh cá nhân người mua |  |
| 13 | inv.buyer_bank_account | Không | string | Số tài khoản người mua | “042661820000211” |
| 14 | inv.buyer_bank_name | Không | string | Tên ngân hàng của stk | “Ngân hàng ABB” |
| 15 | inv.payment_method | Có | string | Hình thức thanh toán (xem lưu ý bên dưới) Có thể là 1 trong các giá trị sau: - TM: Tiền mặt - CK: Chuyển khoản - TM/CK: Tiền mặt/Chuyển khoản - DTCN: Đối trừ công nợ - KTT: Không thu tiền - TTD: Thẻ tín dụng - HBT: Hàng biếu tặng - TQL: Thu qua lương - L/C: L/C - TTR: TTR - TM/CK/BTCN: Tiền mặt hoặc chuyển khoản hoặc bù trừ công nợ | “TM/CK”, |
| 16 | inv.discount | Không | number | Số tiền chiết khấu | 0 |
| 17 | inv.sum_v | Có | number | Tổng tiền chưa thuế, đã chiết khấu (đã quy đổi VNĐ) | 10000 |
| 18 | inv.sum_sale_v | Có | number | Tổng tiền hàng chưa thuế, chưa chiết khấu (đã quy đổi VNĐ) | 100000 |
| 19 | inv.vat_v | Có nếu là hóa đơn GTGT | number | Tổng tiền thuế (đã quy đổi VNĐ) | 1000 |
| 20 | inv.total_v | Có | number | Thành tiền sau thuế (đã quy đổi VNĐ) | 10000 |
| 21 | inv.total_v_in_words | Có | string | Thành tiền sau thuế bằng chữ (VNĐ) | “Một trăm nghìn đồng” |
| 22 | inv.seq | Không | string | Số đơn hàng | “000001” |
| 23 | inv.sid | Có | string | Mã đơn hàng theo merchant. Không được phép trùng, ví dụ rule (merchant_id-mã đơn hàng) | “6732-JJNSHAHIQ121” |
| 24 | inv.sum | Có | number | Tổng tiền chưa thuế, đã chiết khấu (nguyên tệ) | 100000 |
| 25 | inv.sum_sale | Có | number | Tổng tiền hàng chưa thuế, chưa chiết khấu (nguyên tệ) | 100000 |
| 26 | inv.vat | Có nếu là hóa đơn GTGT | number | Tổng tiền thuế nguyên tệ | 1000 |
| 27 | inv.total | Có | number | Tổng tiền thanh toán bao gồm tiền thuế nguyên tệ | 1000 |
| 28 | inv.form | Có | string | Mẫu hóa đơn đăng ký sử dụng trên hệ thống (xem lưu ý bên dưới) | “1” |
| 29 | inv.aun | Không (only FPT) | number | Sử dụng xác định phương thức quản lý số hóa đơn sẽ do hệ thống nào cấp số: + Trường hợp DN muốn tự quản lý việc cấp số trên hệ thống DN: “aun”: 1, bắt buộc phải có số hóa đơn tại thẻ“seq” + Trường hợp chọn eInvoice tự động cấp số khi nhận dữ liệu từ hệ thống quản lý của DN: “aun”: 2 |  |
| 30 | inv.sign | Không (only FPT) | Number | Sử dụng đối với hóa đơn Xuất hoàn trả: + "sign": -1: Đánh dấu hóa đơn là hóa đơn xuất hoàn trả + "sign": 1 hoặc không có thẻ: Hóa đơn thông thường |  |
| 31 | inv.type_ref | Không (only FPT) | number | Thẻ xác định loại hóa đơn đang sử dụng: - 1: Hóa đơn theo TT78 - Bỏ trống: Hóa đơn theo TT32 |  |
| 32 | inv.stax | Có | string | Mã số thuế người bán (xem lưu ý bên dưới) | “2392190986” |
| 33 | inv.type | Có (only FPT, Vietel) | string | Loại hóa đơn | “01GTKT” |
| 34 | inv.is_send_mail | Không | boolean | Có gửi email khi phát hành thành công không |  |
| 35 | inv.receiver_name | Không | string | Tên người nhận email |  |
| 36 | inv.receiver_email | Không | string | Địa chỉ nhận email, phân tách bởi dấu; (chấm phẩy) ( Chỉ thực hiện gửi ở Product ) | “abv@gmai.com;bdf@gmail.com” |
| 37 | inv.items[].line | Có | number | Số thứ tự dòng hàng hóa | 1 |
| 38 | inv.items[].type | Có | number \| string | (xem lưu ý bên dưới) Loại hàng hóa 1: Hàng hóa thường 2: Khuyến mại 3: Chiết khấu 4: Ghi chú/diễn giải 5: Hàng hóa đặc thù vận tải | 1 |
| 39 | inv.items[].code | Không | string | Mã hàng hóa |  |
| 40 | inv.items[].name | Không | string | Tên hàng hóa |  |
| 41 | inv.items[].unit | Không | string | Đơn vị hàng hóa | “Phần” |
| 42 | inv.items[].quantity | Không | number | Số lượng hàng hóa |  |
| 43 | inv.items[].price | Không | number | Đơn giá hàng hóa |  |
| 44 | inv.items[].perdiscount | Không | number | Tỷ lệ % chiết khấu |  |
| 45 | inv.items[].amtdiscount | Không | number | Số tiền chiết khấu |  |
| 46 | inv.items[].amount | Không | number | Thành tiền từng dòng hàng hóa dịch vụ |  |
| 47 | inv.items[].amountn | Không | number | Thành tiền sau chiết khấu (= amount - amtdiscount) |  |
| 48 | inv.items[].vrt | Có nếu là hóa đơn GTGT | string | Loại thuế suất, giá trị tùy thuộc vào nhà cung cấp (xem lưu ý bên dưới) | “0”, “5”, “10” |
| 49 | inv.items[].vat | Có nếu là hóa đơn GTGT | number | Số tiền VAT từng hàng hóa |  |
| 50 | inv.items[].total | Không | number | Tổng tiền bao gồm VAT từng hàng hóa |  |
| 51 | inv.tax_rate_info[].vrt | Có nếu là hóa đơn GTGT (only MISA, Viettel) | string | Tổng hợp loại thuế suất: KCT(MISA) \|\| -1 (Viettel): chịu thuế KKKNT (MISA) \|\| -2 (Viettel): kê khai nộp thuế 0%: thuế suất 0% 5%: thuế suất 5% 8%: thuế suất 8% 10%: thuế suất 10% KHAC:x%: loại thuế suất khác (Ví dụ: KHAC:3.5%) | “10%” |
| 52 | inv.tax_rate_info[].amountn | Có nếu là hóa đơn GTGT (only MISA, Viettel) | number | Tổng tiền trước thuế của dòng hàng theo nhóm thuế suất |  |
| 53 | inv.tax_rate_info[].vat | Có nếu là hóa đơn GTGT (only MISA, Viettel) | number | Tổng tiền thuế của dòng hàng |  |

Sự khác nhau về giá trị theo nhà cung cấp trong một số trường khi tạo hóa đơn

| Tên trường | 1Invoice | FPT | Misa | Viettel |
| --- | --- | --- | --- | --- |
| inv.serial | Bắt buộc | Không bắt buộc | Bắt buộc | Bắt buộc |
| inv.invoice_date | Bắt buộc | Bắt buộc | Bắt buộc | Không bắt buộc |
| inv.stax | Truyền MST | Truyền MST | Truyền MST | Truyền chuỗi rỗng “” |
| inv.payment_method | Không bắt buộc phải là “TM/CK”, “CK”... mà có thể tùy biến ví dụ “QR”, “CARD” | Bắt buộc phải là “TM”, “CK”, “TM/CK”.... | Không bắt buộc phải là “TM/CK”, “CK”... mà có thể tùy biến ví dụ “QR”, “CARD” | Không bắt buộc phải là “TM/CK”, “CK”... mà có thể tùy biến ví dụ “QR”, “CARD” |
| inv.form | “1” | “1” (không truyền trường này nếu đã truyền serial) | “” | template_code trả từ danh sách ký hiệu hóa đơn |
| inv.type | Không bắt buộc | Bắt buộc | Không bắt buộc | Bắt buộc |
| inv.items[].type | 1 Tính chất hàng hóa: - Hàng hóa dịch vụ ( giá trị tchat là 1) - Khuyến mại (giá trị tchat là 2) - Chiết khấu thương mại (giá trị tchat là 3) - Ghi chú/ diễn giải (giá trị tchat là 4) | “” Hình thức hàng hóa có 4 loại: - MT: Ghi chú, diễn giải - CK: Chiết khấu thương mại - KM: Khuyến mãi - Truyền rỗng: Thông thường | 1 Tính chất hàng hóa 1: Hàng hóa thường 2: Khuyến mại 3: Chiết khấu 4: Ghi chú/diễn giải 5: Hàng hóa đặc thù vận tải | “” - Null hoặc 1- Hàng Hóa (Sinh STT, bắt buộc phải nhập số lượng, đơn giá) - 2: Ghi chú (Không sinh STT và không cộng tiền vào tổng tiền thanh toán) - 3: Chiết khấu (Không sinh STT, không cần nhập số lượng, đơn giá và thêm isIncreaseItem = false để xác định giảm tiền) - 4: Phí khác (Không sinh STT, không nhập số lượng, đơn giá) - 5: Khuyến mại (Sinh STT, bắt buộc phải nhập số lượng, đơn giá) - 6: Hàng hóa đặc trưng, nếu truyền hàng hóa đặc trưng (ND 70) thì các trường thông tin bắt buộc xem danh sách bên dưới |
| inv.items[].vrt | “8”, “10” … Truyền các giá trị cố định sau: 10: Thuế suất 10% 8: Thuế suất 8% 5: Thuế suất 5% 0: Thuế suất 0% -1: Không chịu thuế -2: Không kê khai nộp thuế Trường hợp phát sinh thêm thuế suất khác ngoài danh sách liên hệ với 1Invoice Bắt buộc truyền nếu tchat là 1,2,3 Không bắt buộc nếu tchat là 4 | “8”, “10” … Loại thuế suất: ( 0, 5, 8, 10, -1, -2) + 0: thuế suất 0% + 5: thuế suất 5% + 8: thuế suất 8% + 10: thuế suất 10% + -1: Không chịu thuế + -2: Không kê khai nộp thuế Khác 6 loại thuế suất trên: thuế suất Khác | “ 8% ”, “ 10% ” … KCT: chịu thuế KKKNT: kê khai nộp thuế 0%: thuế suất 0% 5%: thuế suất 5% 8%: thuế suất 8% 10%: thuế suất 10% KHAC:x%: loại thuế suất khác (Ví dụ: KHAC:3.5%) | “8”, “10” … Thuế suất của hàng hóa, dịch vụ (-2: không thuế, -1: không kê khai, 0: 0%, 5: 5%, 8: 8%, 10: 10%...). |

Xuất hóa đơn cho khách lẻ

| Trường | 1Invoice | FPT | Misa | Viettel |
| --- | --- | --- | --- | --- |
| Tên đơn vị ( inv.buyer_legal_name) | Không bắt buộc | Bắt buộc | Không bắt buộc | Không bắt buộc |
| Địa chỉ ( inv.buyer_address) | Không bắt buộc | Bắt buộc Có thể để nội dung: “Khách không lấy hóa đơn” | Không bắt buộc | Không bắt buộc |

Response:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| data.search_code | string | Mã để người dùng tra cứu hóa đơn |
| data.seq | number | Số hóa đơn |
| data.tax_authority_code | string | Mã cơ quan thuế |
| data.vpid | string | Id dùng để xem PDF hoặc ký hóa đơn |
| data.error_code | string | Mã lỗi nếu có (Có mã lỗi: Tạo Fail, không có mã lỗi: Tạo thành công) |
| data.transaction_id | string | Mã giao dịch nếu có |

Lưu ý: sự khác nhau giữa dữ liệu respone khi tạo hóa đơn (: có,: không)

| Trường | 1Invoice | FPT | Misa | Viettel |
| --- | --- | --- | --- | --- |
| Mã cơ quan thuế |  |  |  |  |
| Mã tra cứu |  |  |  |  |
| Số hóa đơn |  |  |  |  |

Sample:

```json
{
  "data": {
    "search_code": "9A97B32B",
    "seq": 567,
    "tax_authority_code": "M1-25-RV1DV-00000009403"
  },
  "success": true,
  "message": null
}
```

Curl sample:

1. 1Invoice

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/create-invoice' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998' \ --header 'Content-Type: application/json' \ --data '{ "lang": "vi", "inv": { "serial": "1C25MTS", "invoice_date": "2025-08-12T05:06:13", "currency": "VND", "ex_rate": 1, "buyer_name": "Lê Thanh Dũng", "buyer_legal_name": "1Invoice - Kiểm thử HĐĐT không mã", "buyer_tax": "0106026495-998", "buyer_address": "Số nhà 16, ngõ 269/1, đường Giáp Bát, Phường Hoàng Mai, TP Hà Nội", "buyer_email": "", "payment_method": "QR", "buyer_bank_account": "", "buyer_bank_name": "", "sum_v": 81500, "vat_v": 8150, "total_v": 89650, "type": "01GTKT", "sid": "160725-8238-JFSFA122", "sum": 81500, "vat": 8150, "total": 89650, "total_v_in_words": "tám mươi chín nghìn sáu trăm năm mươi đồng", "form": "1", "aun": 2, "sign": 1, "type_ref": 1, "stax": "0106026495-998", "items": [ { "line": 1, "code": "172", "name": "Mì xào trứng", "unit": "Phần", "quantity": 1, "price": 50000, "perdiscount": 0, "amtdiscount": 0, "amount": 50000, "amountn":50000, "vrt": "10", "vat": 5000, "total": 55000 }, { "line": 2, "code": "173", "name": "Bánh mì ốp la", "unit": "Phần", "quantity": 1, "price": 30000, "perdiscount": 0, "amtdiscount": 0, "amount": 30000, "amountn":30000, "vrt": "10", "vat": 3000, "total": 33000 }, { "line": 3, "code": "262", "name": "Sticker", "unit": "Phần", "quantity": 1, "price": 1500, "perdiscount": 0, "amtdiscount": 0, "amount": 1500, "amountn":1500, "vrt": "10", "vat": 150, "total": 1650 } ] } }'
```

2. 1Invoice:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/one-invoice' \ --header 'X-Tax-Code: 0106026495-998' \ --header 'X-Bank: quangtran' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --data-raw '{ "inv": { "serial": "1C25MTS", "invoice_date": "2025-08-25", "currency": "VND", "ex_rate": 1, "buyer_name": "Nguyễn Công Đức", "buyer_legal_name": "CÔNG TY 1Invoice", "buyer_tax": "0106026495-999", "buyer_address": "Giáp Bát, Hoàng Mai, Hà Nội", "buyer_email": "abc@gmail.com", "buyer_bank_account": "100003131", "buyer_bank_name": "Ngân hàng TMCP Á Châu - ACB", "payment_method": "TM/CK", "discount": 0, "sum_v": 610000, "vat_v": 48800, "total_v": 658800, "seq": "", "sid": "123456114x", "items": [ { "line": 1, "type": 1, "code": "HH001", "name": "Hàng hóa 001", "unit": "Phần", "quantity": 1, "price": 120000, "perdiscount": 0, "amtdiscount": 0, "amount": 120000, "vrt": 8, "vat": 9600, "total": 129600 }, { "line": 2, "type": 1, "code": "HH002", "name": "Hàng hóa 002", "unit": "Phần", "quantity": 2, "price": 245000, "perdiscount": 0, "amtdiscount": 0, "amount": 490000, "vrt": 8, "vat": 39200, "total": 529200 } ] } } '
```

3. Misa

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/misa/create-invoice?type_invoice=icr' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: {{vault:bearer-token}}' \ --header 'x-tax-code: 2222222222-788' \ --header 'Content-Type: application/json' \ --data '{ "lang": "vi", "inv": { "serial": "1C25MTS", "invoice_date": "2025-12-18T02:39:49", "currency": "VND", "ex_rate": 1, "buyer_name": "Khách lẻ", "buyer_legal_name": "", "buyer_address": "", "buyer_phone_number": "0999988754", "payment_method": "TM/CK", "buyer_bank_account": "", "buyer_bank_name": "", "sum_v": 136000, "sum_sale_v": 136000, "vat_v": 0, "total_v": 136000, "sid": "4324823-EDASDHLAKS-312312", "sum": 136000, "sum_sale": 136000, "vat": 0, "total": 136000, "total_v_in_words": "Một trăm ba mươi sáu nghìn đồng", "form": "1", "aun": 2, "sign": 1, "type_ref": 1, "sendfile": 1, "notsendmail": "", "is_send_mail": true, "receiver_name": "Khách lẻ", "stax": "2222222222-788", "non_tax_zone": null, "tax_rate_info": [ { "vrt": "0%", "amountn": 136000, "vat": 0 } ], "items": [ { "line": 1, "type": 1, "code": "2925 ", "name": "Bò nhúng giấm", "unit": "Cốc", "quantity": 4, "price": 25000, "perdiscount": 0, "amtdiscount": 0, "amount": 100000, "amountn": 100000, "vrt": "0%", "vat": 0, "total": 100000 }, { "line": 2, "type": 1, "code": "2928 ", "name": "Test1111", "unit": "Phần", "quantity": 3, "price": 12000, "perdiscount": 0, "amtdiscount": 0, "amount": 36000, "amountn": 36000, "vrt": "0%", "vat": 0, "total": 36000 } ] } }'
```

4. FPT

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/fpt/create-invoice?type_invoice=icr' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwMzAzODgzMjY2LmFwaSIsIm1haWwiOiJ0dXRtMTBAZnB0LmNvbSIsImZuIjoiQVBJIiwib3UiOjEsIm9uIjoiQ8OUTkcgVFkgVE5ISCBKT0xMSUJFRSBWSeG7hlQgTkFNIiwib3JnIjp7InRlbF9oYXNfdGF4YyI6IjAwMDAiLCJhZGRyX2hhc190YXhjIjoiTOG6p3UgNSwgVMOyYSBuaMOgIFNDSUMsIHPhu5EgMTYsIMSRxrDhu51uZyBUcsawxqFuZyDEkOG7i25oLCBQaMaw4budbmcgMDYsIFF14bqtbiAzLCBUUCBI4buTIENow60gTWluaCIsIm9uX2hhc190YXhjIjoiQ8OUTkcgVFkgVE5ISCBKT0xMSUJFRSBWSeG7hlQgTkFNIiwibGVnYWxfbmFtZSI6IkFCQyIsImxlZ2FsX2dlbmRlciI6IjEiLCJsZWdhbF9iaXJ0aGR0IjoiMTk4MC0wMS0wMSIsImxlZ2FsX3RlbCI6IjAwMDAwIiwibGVnYWxfbnVtIjoiMDAwMDAwMTIzMTIzIiwibGVnYWxfcGFzc3BvcnQiOm51bGwsImxlZ2FsX25hdGlvbmFsaXR5IjoiIiwiYnVkZ2V0X3JlbGF0aW9uaWQiOm51bGwsIm9uIjoiQ8OUTkcgVFkgVE5ISCBKT0xMSUJFRSBWSeG7hlQgTkFNIiwib3QiOiIwMzAzODgzMjY2IiwiYWRkIjoiTOG6p3UgNSwgVMOyYSBuaMOgIFNDSUMsIHPhu5EgMTYsIMSRxrDhu51uZyBUcsawxqFuZyDEkOG7i25oLCBQaMaw4budbmcgMDYsIFF14bqtbiAzLCBUUCBI4buTIENow60gTWluaCIsImFkZHIiOiJM4bqndSA1LCBUw7JhIG5ow6AgU0NJQywgc-G7kSAxNiwgxJHGsOG7nW5nIFRyxrDGoW5nIMSQ4buLbmgsIFBoxrDhu51uZyAwNiwgUXXhuq1uIDMsIFRQIEjhu5MgQ2jDrSBNaW5oIiwidGVsIjoiMDAwMCIsIm1haWwiOiJ0dXRtMTBAZnB0LmNvbSIsImFjYyI6IiIsImJhbmsiOiIiLCJzaWduIjoyLCJzaWduX3JlY2VpcHQiOjEsInNpZ25fcGl0ZCI6MSwiZGVncmVlX2NvbmZpZyI6MTIzLCJyZWNlaXB0X2RlZ3JlZV9jb25maWciOjExOSwidGF4byI6IjcxNzAwIiwidGF4b25hbWUiOiJUSFXhur4gVEjDgE5IIFBI4buQIEjhu5IgQ0jDjSBNSU5IIiwicGF4byI6IjcxNzAwIiwicGF4b25hbWUiOiJUSFXhur4gVEjDgE5IIFBI4buQIEjhu5IgQ0jDjSBNSU5IIiwic2VxIjoyLCJzZXFfcGl0ZCI6Miwic2VxX3JlY2VpcHQiOjIsImNmcGl0ZF9zaWduX2Nvb3JkaW5hdGUiOiIiLCJwd2RfaGFyZF9ydWxlIjoxLCJpbnZfYXV0aG9yaXphdGlvbiI6MiwidXNlX3BldHJvIjoyLCJ1c2VfbXVsdGlwbGVfb3UiOjIsInByb3ZfbiI6bnVsbCwiZGlzdF9uIjpudWxsLCJ3YXJkX24iOm51bGwsInVzZV9ncm91cF9wZXJtaXNzaW9uIjowLCJjYW5fcmVwX2Fkal93bm9faW52X2xvZ2ljIjoxLCJ1c2luZ190cmFuc2Zvcm1fZ29vZHNfY2F0ZSI6MCwiY2ZnX2lkbGUiOm51bGwsInVzZV9mZWUiOjB9LCJzY2hlbWEiOiJpMDMwMzg4MzI2NiIsInRheGMiOiIwMzAzODgzMjY2Iiwic3RhdHVzIjp7InN0YXR1c2FwcHIiOjIsInN0YXR1c3ByaW50IjowLCJzdGF0dXNpbnB1dGludiI6MCwic3RhdHVzeGxzZGF0ZSI6MCwic3RhdHVzX3NlcV93YXkiOjEsImNvbmZpcm1fbWFpbF9waXRkIjoyLCJpc1VzZVBpdGQiOnRydWUsImlzVXNlSW52b2ljZSI6dHJ1ZSwiaXNfdXNlX3JlY2VpcHQiOnRydWUsImlzX3VzZV9pY3IiOnRydWUsImFkal9vbmx5X2FkZCI6MSwianNvbl90ZW1wbGF0ZSI6MiwiaWNyX3NlcV9zcGVjIjoyfSwibXN0IjoiMDMwMzg4MzI2NiIsInRheCI6IjAzMDM4ODMyNjYiLCJwYXJlbnRfdGF4IjpudWxsLCJwYXJlbnRfbXN0IjpudWxsLCJzYyI6MCwic2N0IjowLCJuYSI6MiwibnAiOjUsIm5xIjoyLCJudW1fZm9ybWF0Ijp7InJlY2VpcHQiOnsibmEiOjIsIm5wIjo1LCJucSI6Mn19LCJpdHlwZSI6IjAxR1RLVCIsImFhZCI6ZmFsc2UsInNzbyI6ZmFsc2UsImFwcF92ZXJzaW9uIjoiMyIsImFwaSI6MSwibW9iaWxlIjpudWxsLCJhZGpfb25seV9hZGQiOjEsImlzX21pbnV0ZXMiOjIsInBlcnNvbl9pbmNvbWVfdGF4X2RvYyI6MCwiaGFzX2ludm9pY2Vfcm9sZSI6MSwidXNlX3JlY2VpcHQiOjAsImlkX3Nlc3Npb24iOiI0Zjg5ZWU2ZC1iNWM4LTQwMzEtYTczMi1lYmZmYTYxMWJkMjMiLCJhdXRvX3NpZ25fbWluIjoyLCJyb2xlIjpbMSwyLDMsNCw1LDYsNyw4LDksMTAsMTIsMTMsMTQsMTUsMTYsMTcsMTgsMTksMjAsMjEsMjIsMzUsMzYsMzcsMzgsNDAsNDEsNDQsNDUsNDYsNjcsNjgsNjldLCJwYXRoIjpbIi9vdXMiLCIvZWRpIiwiL2VtYSIsIi9ldGUiLCIvdXNlIiwiL2FkcyIsIi9hYWQiLCIvY29sIiwiL2R0bCIsIi94bHMiLCIvb3JjIiwiL29yZyIsIi9zZXIiLCIvcGV0IiwiL3RheCIsIi9leGMiLCIvbG9jIiwiL2ducyIsIi9panQiLCIvYWp0IiwiL3N1cCIsIi9mZWUiLCIvdGJxIiwiL3N0bSIsIi9zdGciLCJzdGEiLCIvaW52IiwiL3NlYSIsIi9pY3IiLCIvc2VxIiwiL2FwcCIsIi9ycHQiLCIvcnBvIiwiL3JlcCIsIi9yZXBvcnQtaGlzdG9yeSIsIi9hZGoiLCIvaWNhIiwiL3NjYSIsIi9zdGEiLCIvZHNzIiwiL3BkZiIsIi9wcmkiLCIvYmluIiwiL2J0aCIsIi93bm8iLG51bGxdLCJzdGF0ZW1lbnQiOnsiaGFzY29kZSI6IjEsMiIsImludnR5cGUiOiIwMUdUS1QsMDdLUFRRLDAzWEtOQiwwNEhHREwsMDEvVFZFLDAyL1RWRSwxMFRNRFQsMDEvTVRULDAyL01UVCwwMkdUVFQsMDUvTVRULDA4L01UVCIsIm1hX2NxdF9jYXAiOiJNQUNRVCJ9LCJpc19tdXN0X2NoYW5nZV9wYXNzd29yZCI6IjEiLCJzdGFydGVkX3Nlc3Npb25fdGltZSI6IjIwMjUtMTEtMjZUMDk6NTA6MDMuOTg4WiIsImZfYXBpX3NvdXJjZSI6IkFQSSIsImlhdCI6MTc2NDE1MDYwNCwiZXhwIjoxNzY0MjM3MDA0fQ.uViLoNFysaViGhzHInG3D64umZikCoGFxZYznG2mL0I' \ --data-raw '{ "inv": { "serial": "", "currency": "VND", "ex_rate": 1, "buyer_name": "Ngô Vũ Quang", "buyer_legal_name": "Ngô Vũ Quang", "buyer_tax": "8613169560", "buyer_address": "Thành phố Quy Nhơn, Bình Định", "buyer_email": "ngovuquang959@gmail.com", "payment_method": "TM/CK", "buyer_bank_account": "", "buyer_bank_name": "", "sum_v": 297000, "vat_v": 29700, "total_v": 326700, "type": "01GTKT", "sid": "2025-0005-0123", "sum": 297000, "vat": 29700, "total": 326700, "form": "1", "aun": 2, "sign": 1, "type_ref": 1, "stax": "0104128565-999", "items": [ { "line": 1, "code": 24, "name": "[P001] BÒ Đỉnh", "unit": "Phần", "quantity": 3, "price": 99000, "perdiscount": 0, "amtdiscount": 0, "amount": 99000, "vrt": "10", "vat": 9900, "total": 108900, "pricev": 99000, "amountv": 99000, "vatv": 9900, "totalv": 108900, "type": "" } ] } }'
```

## 2.4. Ký hóa đơn

Mục đích: Dùng để ký hóa đơn gửi sang Cơ quan thuế

- **Endpoint:** /sign-contract

- **Method:** POST

Header:

- **Authorization:** Bearer <token từ API đăng nhập>

- **Content-Type:** application/json

X-Tax-Code: [Mã số thuế người bán (cửa hàng…)]

Body:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| id | string | sid hóa đơn (trả về trong từng phần tử của danh sách hóa đơn) |
| inv.stax | string | Mã số thuế người bán |
| inv.start_date | Datetime | Ngày xuất hóa đơn |
| inv.end_date | Datetime | Ngày xuất hóa đơn |

Curl sample:

1. 1Invoice:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/sign-contract' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998' \ --header 'Content-Type: application/json' \ --data '{ "id": "3a1baffc-e577-a496-8a02-35145559c213", "inv": { "stax": "0106026495-998", "start_date": "2025-08-12", "end_date": "2025-08-12" } }'
```

2. 1Invoice

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/one-invoice/sign-contract' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \
```

3.FPT

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/fpt/sign-contract' \ --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwMzE2ODg3MDk5LmFwaTk5OSIsIm1haWwiOiJseXB0ZDNAZnB0LmNvbSIsImZuIjoiYXBpOTk5Iiwib3UiOjIsIm9uIjoiQ8OUTkcgVFkgQ-G7lCBQSOG6pk4gR0nhuqJJIFBIw4FQIEFUT00gOTk5IFRFU1QiLCJvcmciOnsidGVsX2hhc190YXhjIjoiIiwiYWRkcl9oYXNfdGF4YyI6IkhOIiwib25faGFzX3RheGMiOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsImxlZ2FsX25hbWUiOm51bGwsImxlZ2FsX2dlbmRlciI6bnVsbCwibGVnYWxfYmlydGhkdCI6bnVsbCwibGVnYWxfdGVsIjpudWxsLCJsZWdhbF9udW0iOm51bGwsImxlZ2FsX3Bhc3Nwb3J0IjpudWxsLCJsZWdhbF9uYXRpb25hbGl0eSI6bnVsbCwib24iOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsIm90IjoiMDEwNDEyODU2NS05OTkiLCJhZGQiOiJITiIsImFkZHIiOiJITiIsInRlbCI6IiIsIm1haWwiOiIiLCJhY2MiOiIiLCJiYW5rIjoiIiwic2lnbiI6Miwic2lnbl9yZWNlaXB0IjoxLCJzaWduX3BpdGQiOjEsImRlZ3JlZV9jb25maWciOjEyMywicmVjZWlwdF9kZWdyZWVfY29uZmlnIjoxMTksInRheG8iOiIxMDEwMCIsInRheG9uYW1lIjoiVHAuIEjDoCBO4buZaSAtIENoaSBj4bulYyBUaHXhur8ga2h1IHbhu7FjIEkiLCJwYXhvIjoiMTAxMDAiLCJwYXhvbmFtZSI6IlRwLiBIw6AgTuG7mWkgLSBDaGkgY
```

## 2.5. Lấy danh sách hóa đơn

Mục đích: Dùng để lấy danh sách hóa đơn điện tử

- **Endpoint:** /get-invoices

- **Method:** GET

Header:

- **Authorization:** Bearer <token từ API đăng nhập>

- **Content-Type:** application/json

X-Tax-Code: [Mã số thuế người bán (cửa hàng…)]

Param:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| start | number | Vị trí bắt đầu |
| count | number | Số lượng phần tử cần lấy |
| serial | string | Ký hiệu hóa đơn |
| from_date | Datetime | Từ ngày |
| to_date | Datetime | Đến ngày |
| stax | string | Mã số thuế người bán (cửa hàng…) |

Lưu ý: Nhà cung cấp FPT không hỗ trợ phân trang

Sự khác nhau về giá trị theo nhà cung cấp trong một số trường khi lấy danh sách hóa đơn

| Tên trường | 1Invoice | FPT | Viettel |
| --- | --- | --- | --- |
| start | Bắt đầu từ 0, lấy theo vị trí index của phần tử; ví dụ 1 trang số lượng 10 phần tử,thì trang số 2 start=10, trang 3 start=20 | Bắt đầu từ 0, lấy theo vị trí index của phần tử; ví dụ 1 trang số lượng 10 phần tử, trang số 2 thì start=10, trang 3 start=20 | Bắt đầu từ 1, lấy theo trang, ví dụ trang 1 thì start=1, trang 2 start=2 |
| serial | Bắt buộc truyền | Không truyền | Bắt buộc truyền |

Response:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| data[].search_code | string | Mã để người dùng tra cứu hóa đơn |
| data[].invoice_date | Datetime | Ngày phát hành hóa đơn |
| data[].seq | number | Số hóa đơn |
| data[].tax_authority_code | string | Mã cơ quan thuế |
| data[].buyer | string | Tên đơn vị |
| data[].bname | string | Tên người mua |
| data[].total_v | number | Tổng tiền bao gồm thuế |
| data[].vat_v | number | Tiền thuế |
| data[].serial | string | Ký hiệu hóa đơn |
| data[].sid | string | Id hóa đơn |
| data[].vpid | string | Id dùng để xem hóa đơn (nếu có) |
| data[].status | number \| string | Trạng thái hóa đơn |
| data[].status_received | number \| string | Trạng thái phản hồi CQT |
| success | boolean | Trạng thái api |
| total | number | Tổng số phần tử thỏa mãn điều kiện, NCC FPT không có |
| message | string | Nội dung lỗi nếu có |

Trường mã CQT (tax_authority_code) và mã tra cứu (search_code), (: có,: không)

| Trường | 1Invoice | FPT | Viettel |
| --- | --- | --- | --- |
| Mã CQT |  |  | Gọi thêm api lấy mã bí mật (lưu ý bên dưới) |
| Mã tra cứu |  |  | Gọi thêm api lấy mã bí mật |

Sample

```json
{
  "success": true,
  "total": 10,
  "data": [
    {
      "seq": 10,
      "invoice_date": "2025-05-19T00:00:00",
      "buyer": "trang",
      "bname": "trang",
      "total_v": 1100000,
      "vat_v": 100000,
      "status_received": 1,
      "serial": "1C25MTS",
      "search_code": "77C19987",
      "status": 0,
      "tax_authority_code": "M1-25-RV1DV-00000003194",
      "sid": "3a19f963-dd71-5689-56ef-9ea75cd51e55"
    },
    {
      "seq": 9,
      "invoice_date": "2025-05-19T00:00:00",
      "buyer": "trang",
      "bname": "trang",
      "total_v": 1100000,
      "vat_v": 100000,
      "status_received": 4,
      "serial": "1C25MTS",
      "search_code": "5FC2F7EE",
      "status": 0,
      "tax_authority_code": "M1-25-RV1DV-00000003173",
      "sid": "3a19f804-37d1-7e98-6b80-47ff0b4ccc6b"
    }
  ],
  "message": null
}
```

Curl:

1. 1Invoice

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/get-invoices?start=0&count=10&serial=1C25MTS&from_date=2025-05-01&to_date=2025-06-06&stax=0106026495-998' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998'
```

2. 1Invoice:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/one-invoice/get-invoices?start=0&count=10&serial=2C26MAT&from_date=2026-04-15&to_date=2026-04-15&stax=0106026495-998&type_invoice=icr' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998' \ --data ''
```

3. FPT:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/fpt/get-invoices?start=0&count=10&serial=C25TAT&from_date=2025-09-24&to_date=2025-09-24&stax=0104128565-999' \ --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwMzE2ODg3MDk5LmFwaTk5OSIsIm1haWwiOiJseXB0ZDNAZnB0LmNvbSIsImZuIjoiYXBpOTk5Iiwib3UiOjIsIm9uIjoiQ8OUTkcgVFkgQ-G7lCBQSOG6pk4gR0nhuqJJIFBIw4FQIEFUT00gOTk5IFRFU1QiLCJvcmciOnsidGVsX2hhc190YXhjIjoiIiwiYWRkcl9oYXNfdGF4YyI6IkhOIiwib25faGFzX3RheGMiOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsImxlZ2FsX25hbWUiOm51bGwsImxlZ2FsX2dlbmRlciI6bnVsbCwibGVnYWxfYmlydGhkdCI6bnVsbCwibGVnYWxfdGVsIjpudWxsLCJsZWdhbF9udW0iOm51bGwsImxlZ2FsX3Bhc3Nwb3J0IjpudWxsLCJsZWdhbF9uYXRpb25hbGl0eSI6bnVsbCwib24iOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsIm90IjoiMDEwNDEyODU2NS05OTkiLCJhZGQiOiJITiIsImFkZHIiOiJITiIsInRlbCI6IiIsIm1haWwiOiIiLCJhY2MiOiIiLCJiYW5rIjoiIiwic2lnbiI6Miwic2lnbl9yZWNlaXB0IjoxLCJzaWduX3BpdGQiOjEsImRlZ3JlZV9jb25maWciOjEyMywicmVjZWlwdF9kZWdyZWVfY29uZmlnIjoxMTksInRheG8iOiIxMDEwMCIsInRheG9uYW1lIjoiVHAuIEjDoCBO4buZaSAtIENoaSBj4bulYyBUaHXhur8ga2h1IHbhu7FjIEkiLCJwYXhvIjoiMTAxMDAiLCJwYXhvbmFtZSI6IlRwLiBIw6AgTuG7mWkgLSBDaGkgY-G7pWMgVGh14bq_IGtodSB24buxYyBJIiwic2VxIjoyLCJzZXFfcGl0ZCI6Miwic2VxX3JlY2VpcHQiOjIsImNmcGl0ZF9zaWduX2Nvb3JkaW5hdGUiOiIiLCJwd2RfaGFyZF9ydWxlIjoxLCJpbnZfYXV0aG9yaXphdGlvbiI6MiwidXNlX3BldHJvIjoyLCJ1c2VfbXVsdGlwbGVfb3UiOjIsInByb3ZfbiI6bnVsbCwiZGlzdF9uIjpudWxsLCJ3YXJkX24iOm51bGwsInVzZV9ncm91cF9wZXJtaXNzaW9uIjowLCJjYW5fcmVwX2Fkal93bm9faW52X2xvZ2ljIjoxLCJ1c2luZ190cmFuc2Zvcm1fZ29vZHNfY2F0ZSI6MCwiY2ZnX2lkbGUiOm51bGwsInVzZV9mZWUiOjB9LCJzY2hlbWEiOiJpMDMxNjg4NzA5OSIsInRheGMiOiIwMzE2ODg3MDk5Iiwic3RhdHVzIjp7InN0YXR1c2FwcHIiOjIsInN0YXR1c3ByaW50IjowLCJzdGF0dXNpbnB1dGludiI6MCwic3RhdHVzeGxzZGF0ZSI6MCwic3RhdHVzX3NlcV93YXkiOjEsImNvbmZpcm1fbWFpbF9waXRkIjoyLCJpc1VzZVBpdGQiOnRydWUsImlzVXNlSW52b2ljZSI6dHJ1ZSwiaXNfdXNlX3JlY2VpcHQiOnRydWUsImlzX3VzZV9pY3IiOnRydWUsImFkal9vbmx5X2FkZCI6MSwianNvbl90ZW1wbGF0ZSI6MiwiaWNyX3NlcV9zcGVjIjoxfSwibXN0IjoiMDEwNDEyODU2NS05OTkiLCJ0YXgiOiIwMTA0MTI4NTY1LTk5OSIsInBhcmVudF90YXgiOm51bGwsInBhcmVudF9tc3QiOm51bGwsInNjIjowLCJzY3QiOjAsIm5hIjoyLCJucCI6NSwibnEiOjIsIm51bV9mb3JtYXQiOnsicmVjZWlwdCI6eyJuYSI6MiwibnAiOjUsIm5xIjoyfX0sIml0eXBlIjoiMDFHVEtUIiwiYWFkIjpmYWxzZSwic3NvIjpmYWxzZSwiYXBwX3ZlcnNpb24iOiIzIiwiYXBpIjoxLCJtb2JpbGUiOm51bGwsImFkal9vbmx5X2FkZCI6MSwiaXNfbWludXRlcyI6MiwicGVyc29uX2luY29tZV90YXhfZG9jIjowLCJoYXNfaW52b2ljZV9yb2xlIjoxLCJ1c2VfcmVjZWlwdCI6MCwiaWRfc2Vzc2lvbiI6IjU4MGFlOTBlLTAzOGUtNGJjOC04ZmZkLWMwNjJkMGIyYWRkYyIsInJvbGUiOlsxLDIsMyw0LDUsNiw3LDgsOSwxMCwxMiwxMywxNCwxNSwxNiwxNywxOCwxOSwyMCwyMSwyMiwzNSwzNiwzNywzOCw0MCw0MSw0NCw0NSw0Niw2Nyw2OCw2OV0sInBhdGgiOlsiL291cyIsIi9lZGkiLCIvZW1hIiwiL2V0ZSIsIi91c2UiLCIvYWRzIiwiL2FhZCIsIi9jb2wiLCIvZHRsIiwiL3hscyIsIi9vcmMiLCIvb3JnIiwiL3NlciIsIi9wZXQiLCIvdGF4IiwiL2V4YyIsIi9sb2MiLCIvZ25zIiwiL2lqdCIsIi9hanQiLCIvc3VwIiwiL2ZlZSIsIi90YnEiLCIvc3RtIiwiL3N0ZyIsInN0YSIsIi9pbnYiLCIvc2VhIiwiL2ljciIsIi9zZXEiLCIvYXBwIiwiL3JwdCIsIi9ycG8iLCIvcmVwIiwiL3JlcG9ydC1oaXN0b3J5IiwiL2FkaiIsIi9pY2EiLCIvc2NhIiwiL3N0YSIsIi9kc3MiLCIvcGRmIiwiL3ByaSIsIi9iaW4iLCIvYnRoIiwiL3dubyIsbnVsbF0sInN0YXRlbWVudCI6eyJoYXNjb2RlIjoiMSwyIiwiaW52dHlwZSI6IjAxR1RLVCwwMS9NVFQsMDJHVFRULDAyL01UVCwwN0tQVFEiLCJtYV9jcXRfY2FwIjoiVlpRWVkifSwiaXNfbXVzdF9jaGFuZ2VfcGFzc3dvcmQiOiIxIiwic3RhcnRlZF9zZXNzaW9uX3RpbWUiOiIyMDI1LTA5LTI0VDA5OjA4OjM2LjQ2NFoiLCJmX2FwaV9zb3VyY2UiOiJBUEkiLCJpYXQiOjE3NTg3MDQ5MTYsImV4cCI6MTc1ODc5MTMxNn0.kduTqeLdUHs7w4eYPyTYoSX6sYAVwWTOv5ZwueyKVSs' \ --header 'x-tax-code: 0104128565-999' \ --header 'Cookie: d4150655895b8526de84b2ab49c2b9e4=25b23b9c55e22b9e0de3559674a733dd'
```

4. Viettel

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/viettel/get-invoices?count=10&to_date=2025-09-24&start=1&serial=K25MVV&from_date=2025-09-17&stax=0100109106-509' \ --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiIwMTAwMTA5MTA2LTUwOSIsInNjb3BlIjpbIm9wZW5pZCJdLCJleHAiOjE3NTg3MDgwMTgsInR5cGUiOjEsImlhdCI6MTc1ODcwNjgxOCwiaW52b2ljZV9jbHVzdGVyIjoiY2x1c3RlcjEwIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjIyZDQyNTE2LWQ5MGUtNGJjYS05ODA4LWE1YzljYjVjOTJjMSIsImNsaWVudF9pZCI6IndlYl9hcHAifQ.Mx1lPSI5OHurHGl2rbj-zLrErAiZxgkKn4in5Atbei5KdizucjZFJARxCTjbHYw766ZH7yQxq8B8_5bgsFydSp-RSSzfXvq_RahAlM6Lv_FX1P9mSfXB0zHFPX_3JclRLqi-WTSzJkN5Llay5gykGMDOodt4U3PscIe7cacwPQsiRdvqR3_YSngtpVKMVkjBJpHNmXiRF9ClV_HEH7_GYsvNwkMVKcNeFJ4Yx2rH5h9MnmIvJMnttLYHPfu0PblqnXFEhRcA-vFz5guzevDHV_W1zhFlukWmKLvp6rbHTl46m1DaCOWX16GUtVgq93jHSFtwV4_XxqI10EtgdPgsbw' \ --header 'x-tax-code: 0100109106-509' \ --header 'Cookie: d4150655895b8526de84b2ab49c2b9e4=25b23b9c55e22b9e0de3559674a733dd'
```

## 2.6. Lấy thông tin chi tiết hóa đơn

Mục đích: Dùng để lấy thông tin chi tiết 1 hóa đơn

- **Endpoint:** /get-invoice

- **Method:** GET

Header:

- **Authorization:** Bearer <token từ API đăng nhập>

- **Content-Type:** application/json

X-Tax-Code: [Mã số thuế người bán (cửa hàng…)]

Param:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| id | string | sid lúc tạo hóa đơn |

Response

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| data.search_code | string | Mã để người dùng tra cứu hóa đơn |
| data.invoice_date | Datetime | Ngày phát hành hóa đơn |
| data.seq | number | Số hóa đơn |
| data.tax_authority_code | string | Mã cơ quan thuế |
| data.buyer | string | Tên đơn vị |
| data.bname | string | Tên người mua |
| data.total_v | number | Tổng tiền bao gồm thuế |
| data.vat_v | number | Tiền thuế |
| data.serial | string | Ký hiệu hóa đơn |
| data.sid | string | Id hóa đơn |
| data.vpid | string | Id dùng để xem hóa đơn (PDF) |
| data.status | number \| string | Trạng thái hóa đơn |
| data.status_received | number \| string | Trạng thái phản hồi CQT |
| success | boolean | Trạng thái api |

Sample:

```json
{
  "data": {
    "seq": 553,
    "invoice_date": "2025-08-12T00:00:00",
    "sid": "3a1bafb9-4889-9c3c-802b-d3af714d2dc6",
    "bname": "1Invoice - Kiểm thử HĐĐT không mã",
    "total_v": 89650,
    "vat_v": 8150,
    "status_received": 1,
    "serial": "1C25MTS",
    "search_code": "D6FBB673",
    "status": 0,
    "tax_authority_code": "M1-25-RV1DV-00000009378",
    "buyer": "Lê Thanh Dũng"
  },
  "success": true
}
```

Curl sample:

1. 1Invoice

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/get-invoice?id=160725-8238-JFSFA1213' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'origin: http://localhost:3000' \ --header 'x-tax-code: 0106026495-998'
```

2. FPT

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/fpt/get-invoices?stax=0104128565-999&sid=8296-SO000227' \ --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwMzE2ODg3MDk5LmFwaTk5OSIsIm1haWwiOiJseXB0ZDNAZnB0LmNvbSIsImZuIjoiYXBpOTk5Iiwib3UiOjIsIm9uIjoiQ8OUTkcgVFkgQ-G7lCBQSOG6pk4gR0nhuqJJIFBIw4FQIEFUT00gOTk5IFRFU1QiLCJvcmciOnsidGVsX2hhc190YXhjIjoiIiwiYWRkcl9oYXNfdGF4YyI6IkhOIiwib25faGFzX3RheGMiOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsImxlZ2FsX25hbWUiOm51bGwsImxlZ2FsX2dlbmRlciI6bnVsbCwibGVnYWxfYmlydGhkdCI6bnVsbCwibGVnYWxfdGVsIjpudWxsLCJsZWdhbF9udW0iOm51bGwsImxlZ2FsX3Bhc3Nwb3J0IjpudWxsLCJsZWdhbF9uYXRpb25hbGl0eSI6bnVsbCwib24iOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsIm90IjoiMDEwNDEyODU2NS05OTkiLCJhZGQiOiJITiIsImFkZHIiOiJITiIsInRlbCI6IiIsIm1haWwiOiIiLCJhY2MiOiIiLCJiYW5rIjoiIiwic2lnbiI6Miwic2lnbl9yZWNlaXB0IjoxLCJzaWduX3BpdGQiOjEsImRlZ3JlZV9jb25maWciOjEyMywicmVjZWlwdF9kZWdyZWVfY29uZmlnIjoxMTksInRheG8iOiIxMDEwMCIsInRheG9uYW1lIjoiVHAuIEjDoCBO4buZaSAtIENoaSBj4bulYyBUaHXhur8ga2h1IHbhu7FjIEkiLCJwYXhvIjoiMTAxMDAiLCJwYXhvbmFtZSI6IlRwLiBIw6AgTuG7mWkgLSBDaGkgY
```

3. Viettel

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/viettel/get-invoice?stax=0100109106-509&id=8238-SO000185' \ --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiIwMTAwMTA5MTA2LTUwOSIsInNjb3BlIjpbIm9wZW5pZCJdLCJleHAiOjE3NTg3MDgwMTgsInR5cGUiOjEsImlhdCI6MTc1ODcwNjgxOCwiaW52b2ljZV9jbHVzdGVyIjoiY2x1c3RlcjEwIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjIyZDQyNTE2LWQ5MGUtNGJjYS05ODA4LWE1YzljYjVjOTJjMSIsImNsaWVudF9pZCI6IndlYl9hcHAifQ.Mx1lPSI5OHurHGl2rbj-zLrErAiZxgkKn4in5Atbei5KdizucjZFJARxCTjbHYw766ZH7yQxq8B8_5bgsFydSp-RSSzfXvq_RahAlM6Lv_FX1P9mSfXB0zHFPX_3JclRLqi-WTSzJkN5Llay5gykGMDOodt4U3PscIe7cacwPQsiRdvqR3_YSngtpVKMVkjBJpHNmXiRF9ClV_HEH7_GYsvNwkMVKcNeFJ4Yx2rH5h9MnmIvJMnttLYHPfu0PblqnXFEhRcA-vFz5guzevDHV_W1zhFlukWmKLvp6rbHTl46m1DaCOWX16GUtVgq93jHSFtwV4_XxqI10EtgdPgsbw' \ --header 'x-tax-code: 0100109106-509' \ --header 'Cookie: d4150655895b8526de84b2ab49c2b9e4=25b23b9c55e22b9e0de3559674a733dd'
```

## 2.7. Xem hóa đơn dạng file PDF

Mục đích: Dùng để xem hóa đơn đã xuất dạng file PDF

- **Endpoint:** /view-print-invoice

- **Method:** GET

Header:

- **Authorization:** Bearer <token từ API đăng nhập>

- **Content-Type:** application/json

X-Tax-Code: [Mã số thuế người bán (cửa hàng…)]

Param:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| id | string | trường vpid hoặc sid ưu tiên vpid nếu có (trả về trong từng phần tử của danh sách hóa đơn) Đối với Misa dùng trường search_code (mã tra cứu) |
| stax | string | Mã số thuế người bán (cửa hàng…) |
| template_code | string | Mã mẫu hóa đơn (được lấy từ danh sách ký hiệu hóa đơn ở NCC Viettel) |
| from_pos | boolean | Có phải là hóa đơn phát hành từ máy tính tiền (Misa) |

Curl sample:

1. 1Invoice:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/view-print-invoice?id=3a1bafb9-4889-9c3c-802b-d3af714d2dc6' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998'
```

2.1Invoice

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/one-invoice/view-print-invoice?id=3a20a2e0-826d-f10f-805c-6820e9550220&stax=0106026495-998&template_code=1&from_pos=true' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998' \ --data ''
```

2. Misa

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/misa/view-print-invoice?id=B1HNTAR8V__&stax=2222222222-788&template_code=1C25MAT&from_pos=true' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBcHBJZCI6IjEwYjNiZjIxLWRkZDItNGRmOS05YTdlLTRhNzFjZjE2YzM4ZSIsIkNvbXBhbnlJZCI6IjExMTA0MCIsIlJvbGVUeXBlIjoiMSIsIlVzZXJJZCI6IjVmYTBhN2RlLTJlOWQtNGNkNi04YzliLWY4ZDMyZjYzYzA3MCIsIlVzZXJOYW1lIjoidGVzdG1pc2FAeWFob28uY29tIiwiTWlzYUlkIjoiYTkxZjA3ODEtMzE3Ny00NmFmLWI5YmItZjFiOWVmNzY3MjI4IiwiUGhvbmVOdW1iZXIiOiIwOTcxNTAwNzMxIiwiRW1haWwiOiJ0ZXN0bWlzYUB5YWhvby5jb20iLCJUYXhDb2RlIjoiMjIyMjIyMjIyMi03ODgiLCJTZWN1cmVUb2tlbiI6IkNFWTEvMVZNU215RnAzQ1dudEEwbjJvenVGbm44bXljeXVVOXoveGJzL01Sd3BGSVdVeDZRbzBuaUNJMzJEaUkiLCJuYmYiOjE3NTg3MDQxMjQsImV4cCI6MTc2MTI5NjEyNCwiaWF0IjoxNzU4NzA0MTI0LCJpc3MiOiJodHRwczovL21laW52b2ljZS52biIsImF1ZCI6Imh0dHBzOi8vbWVpbnZvaWNlLnZuIn0.zoNRjhvJHRE1P5oIqcQj_bnD3Q55fTB-RIRxdBPkobw' \ --header 'x-tax-code: 2222222222-788' '
```

3.FPT

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/fpt/view-print-invoice?id=8296-SO000227&stax=0104128565-999&from_pos=false' \ --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwMzE2ODg3MDk5LmFwaTk5OSIsIm1haWwiOiJseXB0ZDNAZnB0LmNvbSIsImZuIjoiYXBpOTk5Iiwib3UiOjIsIm9uIjoiQ8OUTkcgVFkgQ-G7lCBQSOG6pk4gR0nhuqJJIFBIw4FQIEFUT00gOTk5IFRFU1QiLCJvcmciOnsidGVsX2hhc190YXhjIjoiIiwiYWRkcl9oYXNfdGF4YyI6IkhOIiwib25faGFzX3RheGMiOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsImxlZ2FsX25hbWUiOm51bGwsImxlZ2FsX2dlbmRlciI6bnVsbCwibGVnYWxfYmlydGhkdCI6bnVsbCwibGVnYWxfdGVsIjpudWxsLCJsZWdhbF9udW0iOm51bGwsImxlZ2FsX3Bhc3Nwb3J0IjpudWxsLCJsZWdhbF9uYXRpb25hbGl0eSI6bnVsbCwib24iOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsIm90IjoiMDEwNDEyODU2NS05OTkiLCJhZGQiOiJITiIsImFkZHIiOiJITiIsInRlbCI6IiIsIm1haWwiOiIiLCJhY2MiOiIiLCJiYW5rIjoiIiwic2lnbiI6Miwic2lnbl9yZWNlaXB0IjoxLCJzaWduX3BpdGQiOjEsImRlZ3JlZV9jb25maWciOjEyMywicmVjZWlwdF9kZWdyZWVfY29uZmlnIjoxMTksInRheG8iOiIxMDEwMCIsInRheG9uYW1lIjoiVHAuIEjDoCBO4buZaSAtIENoaSBj4bulYyBUaHXhur8ga2h1IHbhu7FjIEkiLCJwYXhvIjoiMTAxMDAiLCJwYXhvbmFtZSI6IlRwLiBIw6AgTuG7mWkgLSBDaGkgY-G7pWMgVGh14bq_IGtodSB24buxYyBJIiwic2VxIjoyLCJzZXFfcGl0ZCI6Miwic2VxX3JlY2VpcHQiOjIsImNmcGl0ZF9zaWduX2Nvb3JkaW5hdGUiOiIiLCJwd2RfaGFyZF9ydWxlIjoxLCJpbnZfYXV0aG9yaXphdGlvbiI6MiwidXNlX3BldHJvIjoyLCJ1c2VfbXVsdGlwbGVfb3UiOjIsInByb3ZfbiI6bnVsbCwiZGlzdF9uIjpudWxsLCJ3YXJkX24iOm51bGwsInVzZV9ncm91cF9wZXJtaXNzaW9uIjowLCJjYW5fcmVwX2Fkal93bm9faW52X2xvZ2ljIjoxLCJ1c2luZ190cmFuc2Zvcm1fZ29vZHNfY2F0ZSI6MCwiY2ZnX2lkbGUiOm51bGwsInVzZV9mZWUiOjB9LCJzY2hlbWEiOiJpMDMxNjg4NzA5OSIsInRheGMiOiIwMzE2ODg3MDk5Iiwic3RhdHVzIjp7InN0YXR1c2FwcHIiOjIsInN0YXR1c3ByaW50IjowLCJzdGF0dXNpbnB1dGludiI6MCwic3RhdHVzeGxzZGF0ZSI6MCwic3RhdHVzX3NlcV93YXkiOjEsImNvbmZpcm1fbWFpbF9waXRkIjoyLCJpc1VzZVBpdGQiOnRydWUsImlzVXNlSW52b2ljZSI6dHJ1ZSwiaXNfdXNlX3JlY2VpcHQiOnRydWUsImlzX3VzZV9pY3IiOnRydWUsImFkal9vbmx5X2FkZCI6MSwianNvbl90ZW1wbGF0ZSI6MiwiaWNyX3NlcV9zcGVjIjoxfSwibXN0IjoiMDEwNDEyODU2NS05OTkiLCJ0YXgiOiIwMTA0MTI4NTY1LTk5OSIsInBhcmVudF90YXgiOm51bGwsInBhcmVudF9tc3QiOm51bGwsInNjIjowLCJzY3QiOjAsIm5hIjoyLCJucCI6NSwibnEiOjIsIm51bV9mb3JtYXQiOnsicmVjZWlwdCI6eyJuYSI6MiwibnAiOjUsIm5xIjoyfX0sIml0eXBlIjoiMDFHVEtUIiwiYWFkIjpmYWxzZSwic3NvIjpmYWxzZSwiYXBwX3ZlcnNpb24iOiIzIiwiYXBpIjoxLCJtb2JpbGUiOm51bGwsImFkal9vbmx5X2FkZCI6MSwiaXNfbWludXRlcyI6MiwicGVyc29uX2luY29tZV90YXhfZG9jIjowLCJoYXNfaW52b2ljZV9yb2xlIjoxLCJ1c2VfcmVjZWlwdCI6MCwiaWRfc2Vzc2lvbiI6IjU4MGFlOTBlLTAzOGUtNGJjOC04ZmZkLWMwNjJkMGIyYWRkYyIsInJvbGUiOlsxLDIsMyw0LDUsNiw3LDgsOSwxMCwxMiwxMywxNCwxNSwxNiwxNywxOCwxOSwyMCwyMSwyMiwzNSwzNiwzNywzOCw0MCw0MSw0NCw0NSw0Niw2Nyw2OCw2OV0sInBhdGgiOlsiL291cyIsIi9lZGkiLCIvZW1hIiwiL2V0ZSIsIi91c2UiLCIvYWRzIiwiL2FhZCIsIi9jb2wiLCIvZHRsIiwiL3hscyIsIi9vcmMiLCIvb3JnIiwiL3NlciIsIi9wZXQiLCIvdGF4IiwiL2V4YyIsIi9sb2MiLCIvZ25zIiwiL2lqdCIsIi9hanQiLCIvc3VwIiwiL2ZlZSIsIi90YnEiLCIvc3RtIiwiL3N0ZyIsInN0YSIsIi9pbnYiLCIvc2VhIiwiL2ljciIsIi9zZXEiLCIvYXBwIiwiL3JwdCIsIi9ycG8iLCIvcmVwIiwiL3JlcG9ydC1oaXN0b3J5IiwiL2FkaiIsIi9pY2EiLCIvc2NhIiwiL3N0YSIsIi9kc3MiLCIvcGRmIiwiL3ByaSIsIi9iaW4iLCIvYnRoIiwiL3dubyIsbnVsbF0sInN0YXRlbWVudCI6eyJoYXNjb2RlIjoiMSwyIiwiaW52dHlwZSI6IjAxR1RLVCwwMS9NVFQsMDJHVFRULDAyL01UVCwwN0tQVFEiLCJtYV9jcXRfY2FwIjoiVlpRWVkifSwiaXNfbXVzdF9jaGFuZ2VfcGFzc3dvcmQiOiIxIiwic3RhcnRlZF9zZXNzaW9uX3RpbWUiOiIyMDI1LTA5LTI0VDA5OjA4OjM2LjQ2NFoiLCJmX2FwaV9zb3VyY2UiOiJBUEkiLCJpYXQiOjE3NTg3MDQ5MTYsImV4cCI6MTc1ODc5MTMxNn0.kduTqeLdUHs7w4eYPyTYoSX6sYAVwWTOv5ZwueyKVSs' \ --header 'x-tax-code: 0104128565-999'
```

4.Viettel:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/viettel/view-print-invoice?stax=0100109106-509&id=K25MVV11&template_code=2%2F00138&from_pos=true' \ --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiIwMTAwMTA5MTA2LTUwOSIsInNjb3BlIjpbIm9wZW5pZCJdLCJleHAiOjE3NTg3MDgwMTgsInR5cGUiOjEsImlhdCI6MTc1ODcwNjgxOCwiaW52b2ljZV9jbHVzdGVyIjoiY2x1c3RlcjEwIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjIyZDQyNTE2LWQ5MGUtNGJjYS05ODA4LWE1YzljYjVjOTJjMSIsImNsaWVudF9pZCI6IndlYl9hcHAifQ.Mx1lPSI5OHurHGl2rbj-zLrErAiZxgkKn4in5Atbei5KdizucjZFJARxCTjbHYw766ZH7yQxq8B8_5bgsFydSp-RSSzfXvq_RahAlM6Lv_FX1P9mSfXB0zHFPX_3JclRLqi-WTSzJkN5Llay5gykGMDOodt4U3PscIe7cacwPQsiRdvqR3_YSngtpVKMVkjBJpHNmXiRF9ClV_HEH7_GYsvNwkMVKcNeFJ4Yx2rH5h9MnmIvJMnttLYHPfu0PblqnXFEhRcA-vFz5guzevDHV_W1zhFlukWmKLvp6rbHTl46m1DaCOWX16GUtVgq93jHSFtwV4_XxqI10EtgdPgsbw' \ --header 'x-tax-code: 0100109106-509' \ --header 'Cookie: d4150655895b8526de84b2ab49c2b9e4=25b23b9c55e22b9e0de3559674a733dd'
```

## 2.8. Lấy danh sách ký hiệu hóa đơn

Mục đích: Dùng để lấy danh sách ký hiệu hóa đơn đã đăng ký

- **Endpoint:** /get-invoice-serials

- **Method:** GET

Header:

- **Authorization:** Bearer <token từ API đăng nhập>

- **Content-Type:** application/json

X-Tax-Code: [Mã số thuế người bán (cửa hàng…)]

Param:

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| inv_type | number | Không truyền: lấy tất cả Loại hóa đơn 1: Hóa đơn GTGT 2: Hóa đơn bán hàng 3: Hóa đơn bán tài sản công 4: Hóa đơn bán hàng dự trữ quốc gia 5: Tem vé thẻ 6: Phiếu xuất kho (Kiêm vận chuyển nội bộ, gửi bán đại lý) |
| stax | string | Mã số thuế người bán (Viettel bắt buộc) |

Response

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| data[].year | number | Năm hiện tại (lấy 2 số cuối) |
| data[].inv_type | string | Loại hóa đơn |
| data[].value | string | Giá trị ký hiệu hóa đơn |
| data[].inv_type_name | string | Mô tả ký hiệu hóa đơn |
| data[].template_code | string | Ký hiệu mẫu hóa đơn (Viettel) |

Sample:

```json
{
  "data": [
    {
      "year": 25,
      "inv_type": "1",
      "value": "1C25MTS",
      "inv_type_name": "Hóa đơn giá trị gia tăng - Máy tính tiền"
    },
    {
      "year": 25,
      "inv_type": "1",
      "value": "1C25MSH",
      "inv_type_name": "Hóa đơn giá trị gia tăng - Máy tính tiền"
    },
    {
      "year": 25,
      "inv_type": "1",
      "value": "1C25MMP",
      "inv_type_name": "Hóa đơn giá trị gia tăng - Máy tính tiền"
    }
  ],
  "success": true,
  "message": "Thành công"
}
```

Curl sample:

1. 1Invoice:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/1Invoice/get-invoice-serials?inv_type=1' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998'
```

2. 1Invoice:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/one-invoice/get-invoice-serials?stax=0106026495-998' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998' \ --data ''
```

3.FPT

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/fpt/get-invoice-serials?stax=0104128565-999' \ --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwMzE2ODg3MDk5LmFwaTk5OSIsIm1haWwiOiJseXB0ZDNAZnB0LmNvbSIsImZuIjoiYXBpOTk5Iiwib3UiOjIsIm9uIjoiQ8OUTkcgVFkgQ-G7lCBQSOG6pk4gR0nhuqJJIFBIw4FQIEFUT00gOTk5IFRFU1QiLCJvcmciOnsidGVsX2hhc190YXhjIjoiIiwiYWRkcl9oYXNfdGF4YyI6IkhOIiwib25faGFzX3RheGMiOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsImxlZ2FsX25hbWUiOm51bGwsImxlZ2FsX2dlbmRlciI6bnVsbCwibGVnYWxfYmlydGhkdCI6bnVsbCwibGVnYWxfdGVsIjpudWxsLCJsZWdhbF9udW0iOm51bGwsImxlZ2FsX3Bhc3Nwb3J0IjpudWxsLCJsZWdhbF9uYXRpb25hbGl0eSI6bnVsbCwib24iOiJDw5RORyBUWSBD4buUIFBI4bqmTiBHSeG6okkgUEjDgVAgQVRPTSA5OTkgVEVTVCIsIm90IjoiMDEwNDEyODU2NS05OTkiLCJhZGQiOiJITiIsImFkZHIiOiJITiIsInRlbCI6IiIsIm1haWwiOiIiLCJhY2MiOiIiLCJiYW5rIjoiIiwic2lnbiI6Miwic2lnbl9yZWNlaXB0IjoxLCJzaWduX3BpdGQiOjEsImRlZ3JlZV9jb25maWciOjEyMywicmVjZWlwdF9kZWdyZWVfY29uZmlnIjoxMTksInRheG8iOiIxMDEwMCIsInRheG9uYW1lIjoiVHAuIEjDoCBO4buZaSAtIENoaSBj4bulYyBUaHXhur8ga2h1IHbhu7FjIEkiLCJwYXhvIjoiMTAxMDAiLCJwYXhvbmFtZSI6IlRwLiBIw6AgTuG7mWkgLSBDaGkgY-G7pWMgVGh14bq_IGtodSB24buxYyBJIiwic2VxIjoyLCJzZXFfcGl0ZCI6Miwic2VxX3JlY2VpcHQiOjIsImNmcGl0ZF9zaWduX2Nvb3JkaW5hdGUiOiIiLCJwd2RfaGFyZF9ydWxlIjoxLCJpbnZfYXV0aG9yaXphdGlvbiI6MiwidXNlX3BldHJvIjoyLCJ1c2VfbXVsdGlwbGVfb3UiOjIsInByb3ZfbiI6bnVsbCwiZGlzdF9uIjpudWxsLCJ3YXJkX24iOm51bGwsInVzZV9ncm91cF9wZXJtaXNzaW9uIjowLCJjYW5fcmVwX2Fkal93bm9faW52X2xvZ2ljIjoxLCJ1c2luZ190cmFuc2Zvcm1fZ29vZHNfY2F0ZSI6MCwiY2ZnX2lkbGUiOm51bGwsInVzZV9mZWUiOjB9LCJzY2hlbWEiOiJpMDMxNjg4NzA5OSIsInRheGMiOiIwMzE2ODg3MDk5Iiwic3RhdHVzIjp7InN0YXR1c2FwcHIiOjIsInN0YXR1c3ByaW50IjowLCJzdGF0dXNpbnB1dGludiI6MCwic3RhdHVzeGxzZGF0ZSI6MCwic3RhdHVzX3NlcV93YXkiOjEsImNvbmZpcm1fbWFpbF9waXRkIjoyLCJpc1VzZVBpdGQiOnRydWUsImlzVXNlSW52b2ljZSI6dHJ1ZSwiaXNfdXNlX3JlY2VpcHQiOnRydWUsImlzX3VzZV9pY3IiOnRydWUsImFkal9vbmx5X2FkZCI6MSwianNvbl90ZW1wbGF0ZSI6MiwiaWNyX3NlcV9zcGVjIjoxfSwibXN0IjoiMDEwNDEyODU2NS05OTkiLCJ0YXgiOiIwMTA0MTI4NTY1LTk5OSIsInBhcmVudF90YXgiOm51bGwsInBhcmVudF9tc3QiOm51bGwsInNjIjowLCJzY3QiOjAsIm5hIjoyLCJucCI6NSwibnEiOjIsIm51bV9mb3JtYXQiOnsicmVjZWlwdCI6eyJuYSI6MiwibnAiOjUsIm5xIjoyfX0sIml0eXBlIjoiMDFHVEtUIiwiYWFkIjpmYWxzZSwic3NvIjpmYWxzZSwiYXBwX3ZlcnNpb24iOiIzIiwiYXBpIjoxLCJtb2JpbGUiOm51bGwsImFkal9vbmx5X2FkZCI6MSwiaXNfbWludXRlcyI6MiwicGVyc29uX2luY29tZV90YXhfZG9jIjowLCJoYXNfaW52b2ljZV9yb2xlIjoxLCJ1c2VfcmVjZWlwdCI6MCwiaWRfc2Vzc2lvbiI6IjdmYjk1MTBkLTcyMzYtNDgzZC1hZWRiLWNkOGE4YjdiZTY2YyIsImF1dG9fc2lnbl9taW4iOjIsInJvbGUiOlsxLDIsMyw0LDUsNiw3LDgsOSwxMCwxMiwxMywxNCwxNSwxNiwxNywxOCwxOSwyMCwyMSwyMiwzNSwzNiwzNywzOCw0MCw0MSw0NCw0NSw0Niw2Nyw2OCw2OV0sInBhdGgiOlsiL291cyIsIi9lZGkiLCIvZW1hIiwiL2V0ZSIsIi91c2UiLCIvYWRzIiwiL2FhZCIsIi9jb2wiLCIvZHRsIiwiL3hscyIsIi9vcmMiLCIvb3JnIiwiL3NlciIsIi9wZXQiLCIvdGF4IiwiL2V4YyIsIi9sb2MiLCIvZ25zIiwiL2lqdCIsIi9hanQiLCIvc3VwIiwiL2ZlZSIsIi90YnEiLCIvc3RtIiwiL3N0ZyIsInN0YSIsIi9pbnYiLCIvc2VhIiwiL2ljciIsIi9zZXEiLCIvYXBwIiwiL3JwdCIsIi9ycG8iLCIvcmVwIiwiL3JlcG9ydC1oaXN0b3J5IiwiL2FkaiIsIi9pY2EiLCIvc2NhIiwiL3N0YSIsIi9kc3MiLCIvcGRmIiwiL3ByaSIsIi9iaW4iLCIvYnRoIiwiL3dubyIsbnVsbF0sInN0YXRlbWVudCI6eyJoYXNjb2RlIjoiMSwyIiwiaW52dHlwZSI6IjAxR1RLVCwwMS9NVFQsMDJHVFRULDAyL01UVCwwN0tQVFEiLCJtYV9jcXRfY2FwIjoiVlpRWVkifSwiaXNfbXVzdF9jaGFuZ2VfcGFzc3dvcmQiOiIxIiwic3RhcnRlZF9zZXNzaW9uX3RpbWUiOiIyMDI1LTEwLTAyVDA2OjU4OjQ3LjI2OVoiLCJmX2FwaV9zb3VyY2UiOiJBUEkiLCJpYXQiOjE3NTkzODgzMjcsImV4cCI6MTc1OTQ3NDcyN30.JtDwh4R3YPZ_TJKyoyRy8voB9TzzrTGoam-BzDVakYE' \ --header 'x-tax-code: 0104128565-999'
```

4. Viettel

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/viettel/get-invoice-serials?stax=0100109106-509' \ --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiIwMTAwMTA5MTA2LTUwOSIsInNjb3BlIjpbIm9wZW5pZCJdLCJleHAiOjE3NTkzODk0NjAsInR5cGUiOjEsImlhdCI6MTc1OTM4ODI2MCwiaW52b2ljZV9jbHVzdGVyIjoiY2x1c3RlcjEwIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6ImI2YzdiZWEyLThhYjgtNDlkYS1iYjc3LWNkMmMwYzU2ZDdiMiIsImNsaWVudF9pZCI6IndlYl9hcHAifQ.Q72HRxdkMiJX1v5qK-gMXZwth2qI6XA9yWkEO8TgCgD-dqOZ2kPRN5sP51fphPoD0VcJR-fedoF9CSC70g8m6tXKAs8ChYFOPYHi7Suc0cITVrzzccrPp1WvFf_6P6rG2SdIzfihu4rbBlcz7VNtMdh5TCPuLQz4eSCdgh7bCZJ4p4br12XFMa5J3QGNn735ZuthZJ_yCW4CSwV3OdCU7V2VXB08ML2bsUG18vxAOTVJkUKzyW3Em8YAn5HVkf4coesyEUXRVeyqr-Pa7Cm095wi-nnkOjVLGJCD6Gl6Ey491aGr-QNMFrfdUL3fhOjn0VmVXNZJS7hdxhUZVzXYaw' \ --header 'x-tax-code: 0100109106-509'
```

5. Misa

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/misa/get-invoice-serials?stax=2222222222-788' \ --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBcHBJZCI6IjEwYjNiZjIxLWRkZDItNGRmOS05YTdlLTRhNzFjZjE2YzM4ZSIsIkNvbXBhbnlJZCI6IjExMTA0MCIsIlJvbGVUeXBlIjoiMSIsIlVzZXJJZCI6IjVmYTBhN2RlLTJlOWQtNGNkNi04YzliLWY4ZDMyZjYzYzA3MCIsIlVzZXJOYW1lIjoidGVzdG1pc2FAeWFob28uY29tIiwiTWlzYUlkIjoiYTkxZjA3ODEtMzE3Ny00NmFmLWI5YmItZjFiOWVmNzY3MjI4IiwiUGhvbmVOdW1iZXIiOiIwOTcxNTAwNzMxIiwiRW1haWwiOiJ0ZXN0bWlzYUB5YWhvby5jb20iLCJUYXhDb2RlIjoiMjIyMjIyMjIyMi03ODgiLCJTZWN1cmVUb2tlbiI6IkNFWTEvMVZNU215RnAzQ1dudEEwbjJvenVGbm44bXljeXVVOXoveGJzL01Sd3BGSVdVeDZRbzBuaUNJMzJEaUkiLCJuYmYiOjE3NTkzODgwMjQsImV4cCI6MTc2MTk4MDAyNCwiaWF0IjoxNzU5Mzg4MDI0LCJpc3MiOiJodHRwczovL21laW52b2ljZS52biIsImF1ZCI6Imh0dHBzOi8vbWVpbnZvaWNlLnZuIn0._TBG4IDFlY_jLAbHpY7voVi9s58a9b6DCuZCfFkc1Yg' \ --header 'x-tax-code: 2222222222-788'
```

## 2.9. Lấy trạng thái tờ khai

Mục đích: Dùng để lấy trạng thái tờ khai kiểm tra xem đã có tờ khai chấp nhận chưa

- **Endpoint:** /core-api/customers/declaration-status

- **Method:** GET

Header:

- **Authorization:** Bearer <token từ API đăng nhập>

- **Content-Type:** application/json

Param:

| Tên trường | Kiểu dữ liệu | Mô tả | Ví dụ |
| --- | --- | --- | --- |
| provider | string | Tên nhà cung cấp đang sử dụng | “1Invoice” |
| taxCode | string | Mã số thuế người bán | “00883243241” |
| sorting | string | Sắp xếp theo trường | “creationTime” |
| sortType | string | Kiểu sắp xếp (DESCEND: Giảm dần, ASCEND: Tăng dần) | “DESCEND” |
| formDate | Datetime | Ngày lập từ ngày | “2024-12-31” |
| toDate | Datetime | Ngày lập đến ngày | “2025-08-11” |
| taxAuthorityFeedback | number | Phản hồi của CQT (1: Tiếp nhận, 2: Không tiếp nhận, 3: Chấp nhận, 4: Không chấp nhận) | 3 |

Response

| Tên trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| data[].id | string | Id tờ khai |
| data[].formality | number | Loại tờ khai, 1: Đăng ký, 2: Thay đổi |
| data[].taxCode | string | Mã số thuế người bán |
| data[].taxAuthorityFeedback | number | Phản hồi của CQT (1: Tiếp nhận, 2: Không tiếp nhận, 3: Chấp nhận, 4: Không chấp nhận) |
| data[].dateCreate | Datetime | Ngày tạo, định dạng ISO 8601 |
| data[].status | number | Trạng thái tờ khai, 0: Chưa gửi, 1: Đã gửi |
| data[].dateSign |  | Ngày ký, định dạng ISO 8601 |

Sample:

```json
{
  "success": true,
  "data": [
    {
      "id": "3a1b94b4-04f9-d3d5-41a8-74dcba5c71d5",
      "formality": 2,
      "taxCode": "0106026495-998",
      "taxAuthorityFeedback": 3,
      "dateCreate": "2025-08-07T00:00:00",
      "status": 1,
      "dateSign": "2025-08-07T03:16:00.126946+00:00"
    },
    {
      "id": "3a1b8512-7a76-ba2c-a6a1-6f656276d399",
      "formality": 2,
      "taxCode": "0106026495-998",
      "taxAuthorityFeedback": 3,
      "dateCreate": "2025-08-04T00:00:00",
      "status": 1,
      "dateSign": "2025-08-04T02:25:13.474248+00:00"
    },
    {
      "id": "3a1b1e62-6618-109a-691f-e286f66c1c97",
      "formality": 2,
      "taxCode": "0106026495-998",
      "taxAuthorityFeedback": 3,
      "dateCreate": "2025-07-15T00:00:00",
      "status": 1,
      "dateSign": "2025-07-15T03:53:51.537946+00:00"
    }
  ]
}
```

Curl sample:

1. 1Invoice

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/core-api/customers/declaration-status?provider=1Invoice&taxCode=0106026495-998&sorting=creationTime&sortType=DESCEND&fromDate=2024-12-31&toDate=2025-08-12&taxAuthorityFeedback=3' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY='
```

2. 1Invoice:

```bash
curl --location 'https://stag-invoice-hub.1invoice.vn/core-api/customers/declaration-status?provider=one-invoice&taxCode=0106026495-998&sorting=creationTime&sortType=DESCEND&fromDate=2025-12-31&toDate=2026-04-15&taxAuthorityFeedback=3' \ --header 'accept: application/json, text/plain, */*' \ --header 'authorization: Bearer O87316arj5+Od3Fqyy5hzdBfIuPk73eKqpAzBSvv8sY=' \ --header 'x-tax-code: 0106026495-998'
```

# PHỤ LỤC

## 1. Trạng thái hóa đơn của nhà cung cấp

### 1.1. 1Invoice

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| 0 | Gốc |
| 1 | Hủy |
| 2 | Điều chỉnh |
| 3 | Thay thế |
| 4 | Giải trình |
| 5 | Bị thay thế |
| 6 | Bị điều chỉnh |

### 1.2. 1Invoice

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| 0 | Gốc |
| 1 | Hủy |
| 2 | Điều chỉnh |
| 3 | Thay thế |
| 4 | Giải trình |
| 5 | Bị thay thế |
| 6 | Bị điều chỉnh |

### 1.3. FPT

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| 1 | Chờ cấp số |
| 2 | Chờ duyệt |
| 3 | Đã duyệt |
| 4 | Đã hủy |

### 1.4. Viettel

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| 1 | Hóa đơn gốc |
| 3 | Hóa đơn thay thế |
| 5 | Hóa đơn điều chỉnh |
| 7 | Hóa đơn xóa bỏ |
| 9 | Hóa đơn chỉnh tiền |

## 2. Trạng thái phản hồi cơ quan thuế

### 2.1. 1Invoice

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| 0 | Chờ duyệt |
| 1 (Cho phép ký) | Chờ ký |
| 2 | Đã ký |
| 3 | Đã gửi |
| 4 | Thành công |
| 5 | Có lỗi |
| 6 | Đang ký |

### 2.2. 1Invoice

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| 0 | Chờ duyệt |
| 1 (Cho phép ký) | Chờ ký |
| 2 | Đã ký |
| 3 | Đã gửi |
| 4 | Thành công |
| 5 | Có lỗi |
| 6 | Đang ký |

### 2.3. FPT

Lưu ý: hóa đơn chưa ký thì sẽ không có trạng thái CQT

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| 0 | Chờ gửi CQT |
| 1 | Đã gửi CQT |
| 2 | Gửi không thành công (Hóa đơn không mã hợp lệ) |
| 8 | Kiểm tra hợp lệ |
| 9 | Kiểm tra không hợp lệ |
| 10 | Đã cấp mã (HĐ có mã hợp lệ đã được CQT cấp mã) |

### 2.4. Viettel

| Mã trạng thái | Tên trạng thái |
| --- | --- |
| INVOICE_HAS_CODE_NOT_SENT | Chưa gửi CQT (hóa đơn có mã CQT) |
| INVOICE_NO_CODE_NOT_SENT | Chưa gửi CQT (hóa đơn không mã CQT) |
| INVOICE_NO_CODE_SENT | Đã gửi CQT (hóa đơn không mã CQT) |
| INVOICE_HAS_CODE_SENT | Đã gửi CQT (hóa đơn có mã CQT) |
| INVOICE_NO_CODE_APPROVED | CQT đã chấp nhận |
| INVOICE_HAS_CODE_APPROVED | CQT đã cấp mã |
| INVOICE_HAS_CODE_DIS_APPROVED | CQT từ chối (hóa đơn có mã CQT) |
| INVOICE_NO_CODE_DIS_APPROVED | CQT từ chốt (hóa đơn không mã CQT) |

## 3. Một số lỗi thường gặp

| Code/Mã lỗi | Mô tả | Cách xử lý |
| --- | --- | --- |
| 88 | sid đã tồn tại trước đó | Thay đổi sid |
| DuplicateInvoiceRefID | sid đã tồn tại trước đó | Thay đổi sid |
| TokenExpiredCode | Token hết hạn | Gọi lại API lấy token |
| InvoiceTemplateNotExist | Mẫu hóa đơn không tồn tại | Serial không tồn tại trong hệ thống |
| SignSoftDream78Exception | Lỗi ký số HSM |  |
| InvoiceDuplicated | Trùng hóa đơn - hóa đơn đã được phát thành |  |

---

# Liên hệ

**TConnect**

- Website: https://tconnect.vn
- Tài liệu: https://docs.tconnect.vn
- Email: info@tconnect.vn
- Hotline / Zalo: 0375927102