API xuất hóa đơn thay thế

Hóa đơn thay thế là gì?

Hóa đơn thay thế được lập khi hóa đơn điện tử đã phát hành và được cơ quan thuế (CQT) tiếp nhận có sai sót cần sửa. Khi hóa đơn thay thế được phát hành thành công, hóa đơn gốc được đánh dấu bị thay thế và không còn hiệu lực.

Khác với hóa đơn điều chỉnh chỉ ghi nhận phần chênh lệch, hóa đơn thay thế ghi đầy đủ nội dung chính xác của hóa đơn mới, bao gồm dòng hàng hóa, số lượng, đơn giá, thuế suất và thông tin người mua.

Ví dụ: Hóa đơn gốc có sai tên hàng và đơn giá ở hai dòng. Thay vì lập các hóa đơn điều chỉnh, bạn có thể lập một hóa đơn thay thế với toàn bộ nội dung đã được sửa chính xác.

Điều kiện của hóa đơn gốc

Hóa đơn gốc được xác định bằng original_invoice_reference_code (chính là reference_code của hóa đơn đã tạo trước đó, cùng provider_account_id).

Hóa đơn gốc phải:

• Đã phát hành thành công và được cơ quan thuế tiếp nhận. Hóa đơn nháp hoặc đang xử lý không thể thay thế.
• Là hóa đơn mới, hóa đơn thay thế hoặc hóa đơn đã được điều chỉnh.
• Chưa bị thay thế hoặc xóa bỏ.
• Chưa từng được thay thế. Mỗi hóa đơn gốc chỉ được thay thế một lần.

Một hóa đơn thay thế có thể tiếp tục được thay thế nếu phát hiện sai sót. Hóa đơn đã được điều chỉnh cũng có thể được thay thế.

Cách hoạt động trong SePay eInvoice API

API POST v1/invoices/replace nhận original_invoice_reference_code cùng toàn bộ nội dung của hóa đơn mới.

API trả về tracking_code ngay sau khi nhận yêu cầu. Việc ký số và gửi hóa đơn lên CQT được xử lý bất đồng bộ. Bạn dùng tracking_code để theo dõi trạng thái qua API theo dõi trạng thái xuất hóa đơn và lấy kết quả cuối cùng.

Mỗi hóa đơn gốc chỉ được thay thế một lần. Nếu hóa đơn thay thế tiếp tục có sai sót, bạn thực hiện điều chỉnh hoặc thay thế chính hóa đơn thay thế đó, không quay lại hóa đơn gốc ban đầu.

API Endpoint

API Request

API Response

{
  "success": true,
  "data": {
    "tracking_code": "3f8b1c2a-7d95-11f1-aef4-52c7e9b4f41b",
    "tracking_url": "https://einvoice-api.sepay.vn/v1/invoices/replace/check/3f8b1c2a-7d95-11f1-aef4-52c7e9b4f41b",
    "message": "Đã tạo yêu cầu xuất hóa đơn thay thế"
  }
}

Xử lý lỗi

Lưu ý sử dụng

• items dùng chung bộ tham số với API xuất hóa đơn điện tử - ghi lại toàn bộ nội dung đúng của hóa đơn, KHÔNG ghi phần chênh lệch. Tổng tiền hóa đơn không được âm.
• Dòng hàng hóa/dịch vụ và hàng khuyến mại (line_type = 1, 2) bắt buộc có item_code, unit và quantity lớn hơn 0.
• buyer là bắt buộc - hóa đơn thay thế lập lại toàn bộ nội dung, bao gồm cả thông tin người mua.
• payment_method không bắt buộc - bỏ trống thì dùng lại phương thức thanh toán của hóa đơn gốc.
• issued_date không bắt buộc và luôn phải là ngày hiện tại (mặc định là thời điểm gọi API).
• is_draft=true tạo bản nháp hóa đơn thay thế - phát hành sau bằng API phát hành hóa đơn với reference_code của bản nháp. is_draft=false xuất và phát hành luôn.
• Sau khi gửi yêu cầu thành công, dùng tracking_url để gọi API theo dõi trạng thái xuất hóa đơn - luôn poll tới khi có kết quả cuối (thành công hoặc thất bại).

Code mẫu

curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/invoices/replace \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"provider_account_id":"0aea3134-da40-11f0-aef4-52c7e9b4f41b","original_invoice_reference_code":"084e179d-d95a-11f0-aef4-52c7e9b4f41b","issued_date":"2026-07-30 00:00:00","reference_code":"3f8b1c2a-7d95-11f1-aef4-52c7e9b4f41b","payment_method":"CK","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":"Thay thế cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026","total_amount":4950000}'

Tham số mẫu

Hóa đơn thay thế cơ bản

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "buyer": {
        "type": "company",
        "name": "Công ty ABC",
        "legal_name": "CÔNG TY TNHH ABC",
        "tax_code": "0101234567",
        "address": "123 Đường A, Quận B, Hà Nội",
        "email": "buyer@example.com"
    },
    "items": [
        {
            "line_number": 1,
            "line_type": 1,
            "item_code": "SP001",
            "item_name": "Sản phẩm A",
            "unit": "cái",
            "quantity": 2,
            "unit_price": 4500000,
            "tax_rate": 10
        }
    ],
    "notes": "Thay thế cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "payment_method": "CK",
    "is_draft": false
}

Hóa đơn thay thế có chiết khấu và dòng chiết khấu thương mại

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "reference_code": "don-thay-the-001",
    "buyer": {
        "type": "personal",
        "name": "Nguyễn Văn A",
        "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh",
        "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": 10,
            "unit_price": 100000,
            "discount_tax": 10,
            "tax_rate": 10
        },
        {
            "line_number": 2,
            "line_type": 3,
            "item_name": "Chiết khấu thương mại",
            "before_discount_and_tax_amount": 50000,
            "tax_rate": 10
        }
    ],
    "notes": "Thay thế cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "payment_method": "TM/CK",
    "is_draft": true
}

Bước tiếp theo

Sau khi gửi yêu cầu thành công và nhận được tracking_code:

1. 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)