Hóa đơn điện tử theo Nghị định 70/2025/NĐ-CP: Những gì developer cần biết

[Hệ thống bán hàng của bạn]
         │
         ▼
POST /openapi/v1/einvoice/create   ──►  [TConnect API]
         │                                      │
         │                         ┌────────────┴────────────┐
         │                    [Xác thực dữ liệu]     [Gửi CQT (Cơ quan thuế)]
         │                         │
         │◄────── invoice_no + pdf_url ──────────┘
         │
[Gửi hóa đơn cho khách hàng]

invoice_data = {
    // Thông tin người bán (từ cấu hình merchant TConnect)
    seller: {
        tax_code: "0123456789",
        name: "CÔNG TY TNHH ABC",
        address: "123 Nguyễn Huệ, Q.1, TP.HCM"
    },
 
    // Thông tin người mua
    buyer: {
        name: "CÔNG TY CP XYZ",
        tax_code: "9876543210",    // Bắt buộc với doanh nghiệp
        address: "456 Lê Lợi, Q.3, TP.HCM",
        email: "[email protected]"
    },
 
    // Thông tin hóa đơn
    invoice_date: "2025-08-10",   // ISO 8601
    invoice_type: "01GTKT",       // Hóa đơn GTGT
    currency: "VND",
    exchange_rate: 1,
 
    // Chi tiết hàng hóa/dịch vụ
    items: [
        {
            line_no: 1,
            item_name: "Phí sử dụng API thanh toán tháng 7/2025",
            unit: "Tháng",
            quantity: 1,
            unit_price: 2000000,
            vat_rate: 10,          // 10% theo luật hiện hành
            amount_before_vat: 2000000,
            vat_amount: 200000,
            amount: 2200000
        }
    ],
 
    // Tổng hóa đơn
    total_amount_before_vat: 2000000,
    total_vat_amount: 200000,
    total_amount: 2200000,
    total_amount_in_words: "Hai triệu hai trăm nghìn đồng chẵn",
 
    // Liên kết đơn hàng (để đối soát)
    reference_order_id: "ORDER_2025_07_001"
}

function create_invoice(base_url, partner_code, access_token, aes_key, invoice_data):
    encrypted = encrypt_payload(invoice_data, aes_key)
 
    POST {base_url}/openapi/v1/einvoice/create
        body: { data: encrypted }
        headers:
            Authorization: "Bearer {access_token}"
            Partner-Code: partner_code
 
    result = decrypt_response(response.data, aes_key)
 
    return {
        invoice_no:   result.invoice_no,    // Số hóa đơn
        invoice_code: result.invoice_code,  // Ký hiệu hóa đơn
        pdf_url:      result.pdf_url,       // Link PDF
        xml_url:      result.xml_url,       // Link XML (gốc điện tử)
        status:       result.status         // ISSUED / PENDING_CQT
    }

function send_invoice_email(invoice_no, customer_email, pdf_url):
    // Gửi email với link PDF hoặc đính kèm file
    send_email(
        to:      customer_email,
        subject: "Hóa đơn điện tử số {invoice_no}",
        body:    """
            Kính gửi Quý khách,
 
            Vui lòng tải hóa đơn điện tử tại: {pdf_url}
 
            Hóa đơn này được phát hành theo quy định của Nghị định 70/2025/NĐ-CP.
        """
    )

function adjust_invoice(base_url, partner_code, access_token, aes_key,
                        original_invoice_no, adjustment_data):
    payload = {
        original_invoice_no: original_invoice_no,
        adjustment_type:     "INCREASE",  // hoặc "DECREASE"
        reason:              "Điều chỉnh số lượng theo xác nhận của khách hàng",
        items:               adjustment_data.items
    }
    POST /openapi/v1/einvoice/adjust

function cancel_invoice(base_url, partner_code, access_token, aes_key,
                        invoice_no, reason):
    payload = {
        invoice_no: invoice_no,
        reason:     reason
    }
    POST /openapi/v1/einvoice/cancel

// IPN endpoint: POST /webhook/ipn
function ipn_handler(request):
    body = parse_json(request)
    txn = decrypt_response(body.data, AES_KEY)
 
    if txn.status == "SUCCESS":
        order = get_order(txn.order_id)
 
        // Phát hành hóa đơn tự động
        invoice = create_invoice(
            invoice_data = build_invoice_from_order(order)
        )
 
        // Cập nhật đơn hàng
        mark_order_paid(order.id, invoice.invoice_no)
 
        // Gửi email hóa đơn
        send_invoice_email(
            invoice.invoice_no,
            order.customer_email,
            invoice.pdf_url
        )
 
    return { status: "ok" }