API xuất hóa đơn điều chỉnh

Hóa đơn điều chỉnh là gì?

Hóa đơn điều chỉnh đượ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. Hóa đơn điều chỉnh không thay thế hoặc hủy bỏ hóa đơn gốc. Hóa đơn gốc vẫn còn hiệu lực, còn hóa đơn điều chỉnh chỉ ghi nhận phần chênh lệch hoặc thông tin cần sửa.

Ví dụ: Hóa đơn gốc có giá trị 10.000.000đ, nhưng giá đúng là 11.000.000đ. Khi đó, bạn lập hóa đơn điều chỉnh tăng với giá trị 1.000.000đ, là phần chênh lệch cần điều chỉnh, không phải lập lại toàn bộ hóa đơn.

Đ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ể điều chỉnh.
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ỏ.

Một hóa đơn đã được điều chỉnh vẫn có thể tiếp tục điều chỉnh nhiều lần.

Các loại hóa đơn điều chỉnh được hỗ trợ

Tham số adjustment_type xác định loại hóa đơn điều chỉnh:

increase - Điều chỉnh tăng
decrease - Điều chỉnh giảm
combined - Điều chỉnh tăng/giảm trên cùng một hóa đơn
info - Điều chỉnh thông tin, không thay đổi giá trị tiền

Chi tiết cách nhập dòng hàng cho từng loại được trình bày tại mục Các loại điều chỉnh (adjustment_type) bên dưới.

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

API POST v1/invoices/adjust nhận original_invoice_reference_code, loại điều chỉnh và các dòng cần điều chỉnh.

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ột hóa đơn có thể được điều chỉnh nhiều lần.

API Endpoint

POST

https://einvoice-api.sepay.vn/v1/invoices/adjust

API Request

provider_account_idstringrequired

ID tài khoản nhà cung cấp (UUID) - phải là tài khoản đã phát hành hóa đơn gốc

original_invoice_reference_codestringrequired

Mã tham chiếu (reference_code) của hóa đơn gốc đã phát hành cần điều chỉnh

adjustment_typeenumrequired

Loại điều chỉnh:

increase: Điều chỉnh tăng
decrease: Điều chỉnh giảm
combined: Điều chỉnh tăng/giảm
info: Điều chỉnh thông tin

issued_datestring

Ngày lập hóa đơn (YYYY-MM-DD HH:mm:ss). Không bắt buộc - mặc định là thời điểm hiện tại. Nếu truyền thì phải là ngày hiện tại.

reference_codestring

Mã tham chiếu của hóa đơn điều chỉnh, 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. Không bắt buộc - nếu bỏ trống, hệ thống dùng lại phương thức thanh toán của hóa đơn gốc (TM/CK khi hóa đơn gốc cũng không có).

TM: Tiền mặt
CK: Chuyển khoản
TM/CK: Tiền mặt và chuyển khoản
KHAC: Khác

is_draftbooleanrequired

Phải là boolean thật (true/false):

true: Xuất nháp (phát hành sau qua API phát hành hóa đơn)
false: Xuất và phát hành luôn

buyerobject

Thông tin người mua.

Bắt buộc khi adjustment_type=info.

Với increase/decrease/combined, nếu không truyền thì sử dụng toàn bộ thông tin người mua của hóa đơn gốc.

itemsarray<object>required

Danh sách dòng điều chỉnh.

increase/decrease/combined: cần ít nhất 1 mặt hàng điều chỉnh.

info: cần ít nhất 1 dòng nội dung.

notesstring

Ghi chú hóa đơn, tối đa 255 ký tự

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 và làm tròn về số nguyên.
Có truyề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.

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

Response thành công (202)

{
  "success": true,
  "data": {
    "tracking_code": "5c2d9e4b-7d96-11f1-aef4-52c7e9b4f41b",
    "tracking_url": "https://einvoice-api.sepay.vn/v1/invoices/adjust/check/5c2d9e4b-7d96-11f1-aef4-52c7e9b4f41b",
    "message": "Đã tạo yêu cầu xuất hóa đơn điều chỉnh"
  }
}

successboolean

dataobject

Xử lý lỗi

400Bad Request

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

401Unauthorized

Thiếu hoặc sai Bearer token, hoặc token đã hết hạn (TOKEN_EXPIRED).

400INVALID_ADJUSTMENT_TYPE

adjustment_type là bắt buộc và phải là một trong: increase, decrease, combined, info.

400INVALID_IS_DRAFT_TYPE

is_draft phải là boolean thật (true/false), không phải chuỗi.

400VALIDATION_ERROR

Dữ liệu dòng hàng không hợp lệ: giá trị âm ngoài loại điều chỉnh tiền, hóa đơn điều chỉnh thông tin có tổng khác 0, không có dòng chênh lệch nào khác 0...

400ISSUED_DATE_INVALID

issued_date không phải là ngày hiện tại.

400INVALID_ISSUED_DATE

issued_date không đúng định dạng Y-m-d H:i:s.

422INVALID_ORIGIN_INVOICE

Hóa đơn gốc không hợp lệ: chưa phát hành, hoặc đã bị thay thế/xóa bỏ.

422REGISTRATION_NOT_TAX_APPROVED

Doanh nghiệp chưa đăng ký HĐĐT hoặc CQT chưa duyệt tờ khai (chỉ check ở production).

422INVOICE_DATE_BEFORE_TAX_APPROVAL

Ngày hóa đơn trước ngày Cơ quan Thuế duyệt tờ khai (chỉ check ở production).

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.

500EINVOICE_ACCOUNT_NOT_FOUND

Không tìm thấy tài khoản xuất hóa đơn điện tử tương ứng provider_account_id.

500QUOTA_HAS_BEEN_USERD_UP

Đã dùng hết hạn ngạch hóa đơn của gói dịch vụ. Cần gia hạn hạn ngạch rồi gọi lại - đừng retry tự động vì lỗi này không tự hết.

500REGISTRATION_NOT_COMPLETE

Công ty chưa hoàn tất đăng ký gói hóa đơn điện tử.

500BILLING_IS_UNPAID

Công ty chưa thanh toán cho gói hóa đơn điện tử.

500Internal Server Error

Lỗi hệ thống khi xử lý yêu cầu.

Các loại điều chỉnh (adjustment_type)

adjustment_type	Loại hóa đơn	Cách nhập dòng hàng
`increase`	Hóa đơn điều chỉnh tăng	Nhập phần chênh lệch TĂNG, giá trị dương
`decrease`	Hóa đơn điều chỉnh giảm	Nhập phần chênh lệch GIẢM, ghi số ÂM theo quy định
`combined`	Hóa đơn điều chỉnh tăng/giảm	Mỗi dòng mang dấu riêng: dương = tăng, âm = giảm
`info`	Hóa đơn điều chỉnh thông tin	Không mang giá trị tiền, tổng phải bằng 0. Nội dung điều chỉnh ghi vào dòng ghi chú (line_type=4)

Thông tin người mua (buyer)

Với increase/decrease/combined: buyer không bắt buộc. Nếu bỏ trống, hệ thống dùng lại toàn bộ thông tin người mua của hóa đơn gốc.
Với info: buyer bắt buộc - đây chính là thông tin đúng cần điều chỉnh (ví dụ địa chỉ mới, mã số thuế đúng).

Lưu ý sử dụng

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).
Với increase/decrease/combined: cần ít nhất một dòng có giá trị khác 0. Các dòng hàng hóa toàn số 0 tự động bị bỏ qua.
Với info: cần ít nhất một dòng nội dung mô tả phần thông tin được điều chỉnh (thường là dòng ghi chú line_type=4), và tổng tiền phải bằng 0.
discount_tax (chiết khấu %) không bao giờ âm - điều chỉnh giảm phần chiết khấu thì truyền thẳng discount_amount số âm.
is_draft=true tạo bản nháp - 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/adjust \
  --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","adjustment_type":"increase","issued_date":"2026-07-30 00:00:00","reference_code":"5c2d9e4b-7d96-11f1-aef4-52c7e9b4f41b","payment_method":"TM/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":"Điều chỉnh tăng mặt hàng Sản phẩm A","unit":"cái","quantity":1,"unit_price":500000,"tax_rate":10,"discount_tax":10,"discount_amount":100000,"before_discount_and_tax_amount":500000,"sub_amount":400000,"tax_amount":40000,"amount":440000}],"notes":"Điều chỉnh tăng đơn giá cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026","total_amount":4950000}'

Tham số mẫu cho các loại điều chỉnh

Hóa đơn điều chỉnh tăng (increase)

json

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "adjustment_type": "increase",
    "items": [
        {
            "line_number": 1,
            "line_type": 1,
            "item_code": "SP001",
            "item_name": "Điều chỉnh tăng mặt hàng Sản phẩm A",
            "unit": "cái",
            "quantity": 1,
            "unit_price": 500000,
            "tax_rate": 10
        }
    ],
    "notes": "Điều chỉnh tăng đơn giá cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "is_draft": false
}

Hóa đơn điều chỉnh giảm (decrease - ghi số âm)

json

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "adjustment_type": "decrease",
    "items": [
        {
            "line_number": 1,
            "line_type": 1,
            "item_code": "SP001",
            "item_name": "Điều chỉnh giảm mặt hàng Sản phẩm A",
            "unit": "cái",
            "quantity": 1,
            "unit_price": -500000,
            "tax_rate": 10
        }
    ],
    "notes": "Điều chỉnh giảm đơn giá cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "is_draft": false
}

Hóa đơn điều chỉnh tăng/giảm (combined - dấu theo từng dòng)

json

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "adjustment_type": "combined",
    "items": [
        {
            "line_number": 1,
            "line_type": 1,
            "item_code": "SP001",
            "item_name": "Điều chỉnh tăng mặt hàng Sản phẩm A",
            "unit": "cái",
            "quantity": 1,
            "unit_price": 300000,
            "tax_rate": 10
        },
        {
            "line_number": 2,
            "line_type": 1,
            "item_code": "SP002",
            "item_name": "Điều chỉnh giảm mặt hàng Sản phẩm B",
            "unit": "cái",
            "quantity": 1,
            "unit_price": -200000,
            "tax_rate": 10
        }
    ],
    "notes": "Điều chỉnh tăng/giảm cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "is_draft": false
}

Hóa đơn điều chỉnh thông tin (info - tổng bằng 0, buyer bắt buộc)

json

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "adjustment_type": "info",
    "buyer": {
        "type": "company",
        "name": "Công ty ABC",
        "legal_name": "CÔNG TY TNHH ABC",
        "tax_code": "0101234567",
        "address": "456 Đường B, Quận C, Hà Nội",
        "email": "buyer@example.com"
    },
    "items": [
        {
            "line_number": 1,
            "line_type": 4,
            "item_name": "Điều chỉnh địa chỉ người mua từ 123 Đường A thành 456 Đường B"
        }
    ],
    "notes": "Điều chỉnh thông tin cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "is_draft": false
}

Điều chỉnh chỉ số tiền dòng bằng thành tiền sau thuế

json

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "adjustment_type": "decrease",
    "items": [
        {
            "line_number": 1,
            "line_type": 1,
            "item_code": "SP001",
            "item_name": "Điều chỉnh giảm mặt hàng Sản phẩm A",
            "unit": "cái",
            "tax_rate": 10,
            "amount": -550000
        }
    ],
    "notes": "Điều chỉnh giảm thành tiền cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "is_draft": false
}

Bước tiếp theo

Sau khi gửi yêu cầu 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 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 chính thức (is_draft=false): Có thể Tải hóa đơn hoặc Xem chi tiết hóa đơn - hóa đơn điều chỉnh có document_type 6/7/8/9 tùy loại, hóa đơn gốc chuyển thành document_type=10 (bị điều chỉnh)