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

Xem hóa đơn demo

API Endpoint

POST

https://einvoice-api.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)

reference_codestring

Mã tham chiếu hóa đơn, phải là duy nhất. Nếu không truyền, hệ thống tự sinh 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ộ

total_amountinteger

Tổng tiền thanh toán cuối cùng của hóa đơn (đã gồm thuế). Không bắt buộc. Nếu truyền thì phải là số nguyên (không có phần thập phân).

Không truyền: hệ thống tự tính từ các dòng hàng (tiền hàng sau chiết khấu + thuế) và làm tròn về số nguyên.
Có truyền: bạn tự tính và tự làm tròn về số nguyên; hệ thống dùng đúng giá trị bạn gửi, KHÔNG kiểm tra / đối chiếu với các dòng hàng. Gửi giá trị có phần thập phân (ví dụ 100000.5) sẽ bị từ chối với lỗi 400.

Cảnh báo (khi có truyền): Bạn tự chịu trách nhiệm về giá trị này. Nếu không khớp tiền hàng + thuế, hóa đơn sẽ hiển thị sai và cơ quan thuế có thể từ chối.

API Response

Success Response (200)

{
  "success": true,
  "data": {
    "tracking_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "tracking_url": "https://einvoice-api.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.

409EINVOICE_DOCUMENT_EXISTED

Hệ thống đã ghi nhận hoá đơn cho mã tham chiếu này. reference_code phải là duy nhất.

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)

Số lượng thập phân

quantity chấp nhận giá trị thập phân (tối đa 2 chữ số sau dấu phẩy).
Phù hợp cho dịch vụ tính giờ (Giờ), cân/đo lường (Kg, m, Lít), hoặc đơn vị tính theo phần (Phần).
Ví dụ: 1.5, 2.75, 0.25.

Lưu ý sử dụng

Để 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

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.

Tổng tiền hóa đơn (total_amount)

total_amount không bắt buộc. Nếu truyền thì phải là số nguyên (không có phần thập phân). Đây là tổng tiền thanh toán cuối cùng của hóa đơn, đã bao gồm thuế.

Trường hợp 1: Không truyền (mặc định)

Hệ thống tự tính total_amount từ các dòng hàng (tiền hàng sau chiết khấu + thuế) và làm tròn về số nguyên.

Trường hợp 2: Có truyền

Bạn tự tính và tự làm tròn về số nguyên trước khi gửi. Hệ thống dùng đúng giá trị bạn gửi, KHÔNG kiểm tra, KHÔNG đối chiếu với tổng tính từ các dòng hàng. Gửi giá trị có phần thập phân (ví dụ 100000.5) sẽ bị từ chối với lỗi 400.

Cảnh báo cho Trường hợp 2 (tự truyền total_amount)

Bạn hoàn toàn chịu trách nhiệm về giá trị bạn truyền. Nếu truyền sai (không khớp tiền hàng + thuế), hóa đơn phát hành sẽ hiển thị tổng tiền sai và cơ quan thuế có thể từ chối. Hãy tự tính và làm tròn chắc chắn trước khi gửi.

Code mẫu

curl --request POST \
  --url https://einvoice-api.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","reference_code":"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ộ","total_amount":4950000}'

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",
      "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",
      "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",
      "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",
      "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",
      "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",
      "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",
      "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