Tạo hóa đơn điện tử

API tạo hóa đơn điện tử nhận dữ liệu hóa đơn, ký số và gửi lên CQT, trả về mã tra cứu. Dùng mã tra cứu để kiểm tra trạng thái hóa đơn.

Xem hóa đơn demo

API Endpoint

POST

https://einvoice-api-sandbox.sepay.vn/v1/invoices/create

API Request

template_codestringrequired

Mã mẫu hóa đơn (lấy từ API chi tiết tài khoản)

invoice_seriesstringrequired

Ký hiệu hóa đơn (lấy từ API chi tiết tài khoản)

issued_datestringrequired

Ngày phát hành (YYYY-MM-DD HH:mm:ss)

currencyenumrequired

Đơn vị tiền tệ:

VND: Việt Nam Đồng
USD: Đô la Mỹ
CAD: Đô la Canada

Mặc định: VND

provider_account_idstringrequired

ID tài khoản nhà cung cấp (UUID)

payment_methodenum

Phương thức thanh toán:

TM: Tiền mặt (Cash)
CK: Chuyển khoản (Bank transfer)
TM/CK: Tiền mặt và chuyển khoản (Cash and bank transfer)
KHAC: Khác (Other)

is_draftboolean

true: Xuất nháp (cần phát hành sau, không tính vào hạn ngạch)
false: Xuất và phát hành luôn

Mặc định: false

buyerobjectrequired

itemsarray<object>required

Danh sách hàng hóa/dịch vụ

notesstring

Ghi chú nội bộ

API Response

Success Response (200)

{
  "success": true,
  "data": {
    "tracking_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "tracking_url": "https://einvoice-api-sandbox.sepay.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "message": "Đã tạo yêu cầu xuất bán hóa đơn điện tử"
  }
}

successboolean

dataobject

Xử lý lỗi

400Bad Request

Thiếu hoặc sai định dạng các trường bắt buộc.

401Unauthorized

Thiếu hoặc sai Bearer token.

403QUOTA_EXCEEDED

Hết hạn ngạch phát hành hóa đơn điện tử. Nâng cấp gói hoặc liên hệ SePay để mở rộng hạn ngạch.

422REGISTRATION_NOT_TAX_APPROVED

Chưa đăng ký HĐĐT hoặc CQT chưa duyệt tờ khai.

422INVOICE_DATE_BEFORE_TAX_APPROVAL

issued_date trước ngày CQT duyệt. Xem tax_authority_approved_date trong GET /v1/provider-accounts.

500Internal Server Error

Lỗi hệ thống khi ký/gửi hóa đơn.

Thông tin thuế suất

tax_rate chỉ bắt buộc truyền khi dùng cho công ty (không cần truyền nếu sử dụng hoá đơn bán hàng)
Trường tax_rate trong items truyền dữ liệu theo như bên dưới:
- -2 (Không chịu thuế)
- -1 (Không kê khai, tính nộp thuế GTGT)
- 0 (0% thuế suất)
- 5 (5% thuế suất)
- 8 (8% thuế suất)
- 10 (10% thuế suất)

Lưu ý sử dụng

Lưu ý chung

Để phát hành, gửi is_draft=false. Nếu chỉ lưu nháp để xem trước, gửi is_draft=true (Nếu chỉ xuất hóa đơn nháp thì sẽ không bị tính vào hạn ngạch hóa đơn điện tử của bạn).
provider_account_id được cung cấp từ API danh sách tài khoản hóa đơn điện tử
Sau khi gửi yêu cầu xuất hóa đơn thành công, sử dụng endpoint được cung cấp qua tracking_url để gọi api theo dõi trạng thái xuất hóa đơn

issued_date

issued_date phải từ tax_authority_approved_date trở đi. Sớm hơn sẽ nhận 422 INVOICE_DATE_BEFORE_TAX_APPROVAL.
Ngày này lấy ở API danh sách tài khoản hoặc chi tiết tài khoản.

Thêm ghi chú trên mẫu hoá đơn

Nếu bạn muốn hiển thị ghi chú trên hoá đơn thì cần thêm môt item với line_type:4 vào items (array), định dạng item line như bên dưới

json

{
  "line_number": 3,
  "line_type": 4,
  "item_name": "Hàng tặng không thu tiền (Đây là ghi chú của bạn)"
}

Cách tính khuyến mại vào tổng tiền

Khi truyền một dòng khuyến mại với line_type = 2, mặc định giá trị sẽ bằng 0 và không được tính vào tổng tiền hóa đơn.
Nếu muốn hàng khuyến mại được tính vào tổng tiền, bạn cần truyền vào giá trị unit_price hoặc các field liên quan đến giá khác (giống như line_type = 1) lớn hơn 0.

Code mẫu

curl --request POST \
  --url https://einvoice-api-sandbox.sepay.vn/v1/invoices/create \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"template_code":"1","invoice_series":"C26TSE","issued_date":"2026-01-26 00:00:00","currency":"VND","provider_account_id":"0aea3134-da40-11f0-aef4-52c7e9b4f41b","payment_method":"TM","is_draft":false,"buyer":{"type":"personal","name":"Công ty TNHH ABC","legal_name":"CÔNG TY CỔ PHẦN ABC","tax_code":"0123456789","address":"123 Đường ABC, Quận 1, TP.HCM","email":"contact@abc.com","phone":"0901234567","buyer_code":"KH-001","national_id":"001234567890"},"items":[{"line_number":1,"line_type":1,"item_code":"SP001","item_name":"Sản phẩm A","unit":"cái","quantity":10,"unit_price":100000,"tax_rate":10,"discount_tax":10,"discount_amount":100000,"before_discount_and_tax_amount":4500000}],"notes":"Ghi chú nội bộ"}'

Tham số mẫu cho các loại hoá đơn

Mẫu hoá đơn bán hàng

json

{
      "template_code": "2",
      "invoice_series": "C25HTV",
      "issued_date": "2025-12-11 08:00:00",
      "currency": "VND",
      "provider_account_id": "{{your-provider-account-id}}",
      "buyer": {
          "name": "Công ty ABC",
          "tax_code": "0101234567",
          "address": "123 Đường A, Quận B, Hà Nội",
          "email": "buyer@example.com",
          "phone": "0900000000",
          "buyer_code": "KH-001",
          "national_id": "001234567890"
      },
      "items": [
          {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000
          }
      ],
      "notes": "Ghi chú hóa đơn",
      "is_draft": true
  }

Mẫu hóa đơn bán hàng có chiết khấu trên tổng đơn

json

{
  "template_code": "2",
  "invoice_series": "C26TSP",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "legal_name": "CÔNG TY CỔ PHẦN ABC",
      "tax_code": "0317887567",
      "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh, Việt Nam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000
      },
      {
          "line_number": 2,
          "line_type": 3,
          "item_name": "Chiết khấu thương mại",
          "before_discount_and_tax_amount": 4500000
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "TM/CK",
  "is_draft": false
}

Mẫu hóa đơn bán hàng có chiết khấu trên sản phẩm (theo phần trăm giảm giá - discount_tax)

json

{
  "template_code": "2",
  "invoice_series": "C26TSP",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "legal_name": "CÔNG TY CỔ PHẦN ABC",
      "tax_code": "0317887567",
      "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh, Việt Nam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000,
          "discount_tax": 2
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "TM",
  "is_draft": false
}

Mẫu hóa đơn bán hàng có chiết khấu trên sản phẩm (theo số tiền giảm giá - discount_amount)

json

{
  "template_code": "2",
  "invoice_series": "C26TSP",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "legal_name": "CÔNG TY CỔ PHẦN ABC",
      "tax_code": "0317887567",
      "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh, Việt Nam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000,
          "discount_amount": 100000
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "CK",
  "is_draft": false
}

Mẫu hóa đơn bán hàng có khuyến mãi

json

{
  "template_code": "2",
  "invoice_series": "C25HTV",
  "issued_date": "2025-12-11 08:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "name": "Công ty ABC",
      "tax_code": "0101234567",
      "address": "123 Đường A, Quận B, Hà Nội",
      "email": "buyer@example.com",
      "phone": "0900000000"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000
      },
      {
          "line_number": 2,
          "line_type": 2,
          "item_code": "KM001",
          "item_name": "Hàng KM",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 0
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "TM",
  "is_draft": true
}

Mẫu hóa đơn giá trị gia tăng

json

{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "legal_name": "CÔNG TY CỔ PHẦN ABC",
      "tax_code": "0317887567",
      "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh, Việt Nam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "CK",
  "is_draft": false
}

Mẫu hóa đơn giá trị gia tăng có chiết khấu trên tổng đơn

json

{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "legal_name": "CÔNG TY CỔ PHẦN ABC",
      "tax_code": "0317887567",
      "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh, Việt Nam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10
      },
      {
          "line_number": 1,
          "line_type": 3,
          "item_name": "Chiết khấu thương mại",
          "tax_rate": 10,
          "before_discount_and_tax_amount": 100000
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "TM/CK",
  "is_draft": false
}

Mẫu hóa đơn giá trị gia tăng có chiết khấu trên sản phẩm (theo phần trăm giảm giá - discount_tax)

json

{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "legal_name": "CÔNG TY CỔ PHẦN ABC",
      "tax_code": "0317887567",
      "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh, Việt Nam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10,
          "discount_tax": 10
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "CK",
  "is_draft": false
}

Mẫu hóa đơn giá trị gia tăng có chiết khấu trên sản phẩm (theo số tiền giảm giá - discount_amount)

json

{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "legal_name": "CÔNG TY CỔ PHẦN ABC",
      "tax_code": "0317887567",
      "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh, Việt Nam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Sản phẩm A",
          "unit": "cái",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10,
          "discount_amount": 100000
      }
  ],
  "notes": "Ghi chú hóa đơn",
  "payment_method": "KHAC",
  "is_draft": false
}

Bước tiếp theo

Sau khi gửi yêu cầu tạo hóa đơn thành công và nhận được tracking_code:

Theo dõi trạng thái xuất hóa đơn - Sử dụng tracking_code để kiểm tra kết quả xử lý (bắt buộc)

Sau khi xác nhận trạng thái thành công

Nếu xuất hóa đơn nháp (is_draft=true): Tiếp tục Phát hành hóa đơn để phát hành chính thức
Nếu xuất hóa đơn chính thức (is_draft=false): Có thể Tải hóa đơn hoặc Xem chi tiết hóa đơn