API tra cứu hóa đơn đầu vào từ cổng thuế: Tự động đồng bộ hóa đơn mua vào

Hóa đơn đầu vào là gì và vì sao cần tự động hóa?

Hóa đơn đầu vào (hóa đơn mua vào) là các hóa đơn điện tử mà doanh nghiệp nhận được từ nhà cung cấp khi mua hàng hóa, dịch vụ. Đây là dữ liệu bắt buộc để:

Kê khai và khấu trừ thuế giá trị gia tăng đầu vào — thiếu hóa đơn là mất quyền khấu trừ.
Hạch toán chi phí và đối chiếu công nợ với nhà cung cấp.
Quyết toán thuế thu nhập doanh nghiệp cuối kỳ.

Vấn đề: kế toán phải đăng nhập thủ công vào cổng Hóa đơn điện tử của Tổng cục Thuế (hoadondientu.gdt.gov.vn), lọc theo từng khoảng ngày rồi tải về từng đợt — lặp lại mỗi tháng, dễ sót, dễ sai. Với doanh nghiệp có hàng trăm hóa đơn/tháng, đây là công việc tốn hàng giờ.

API tra cứu hóa đơn đầu vào của TConnect thay thế toàn bộ thao tác thủ công đó bằng vài lời gọi API.

Cách API hoạt động: "lấy hộ", không can thiệp dữ liệu

Nguyên tắc cốt lõi: hệ thống chỉ lấy hộ đúng hóa đơn của bạn, không sửa, không xử lý, không thay đổi dữ liệu gốc.

Đối tác cung cấp tài khoản cổng thuế (mã số thuế + mật khẩu).
Hệ thống tự động lấy hộ và đồng bộ hóa đơn — cả hóa đơn điện tử lẫn hóa đơn máy tính tiền — về cho bạn, không cần thao tác tay.
Dữ liệu được mã hóa và lưu lại, trả về qua API dưới dạng JSON có cấu trúc — giữ nguyên như trên cổng thuế.

Bất đồng bộ theo thiết kế: Cổng thuế giới hạn mỗi truy vấn khoảng 31 ngày và việc lấy dữ liệu cần thời gian. Vì vậy đồng bộ chạy nền (async): bạn tạo yêu cầu, nhận jobId, rồi hỏi trạng thái đến khi xong.

Luồng tích hợp 5 bước

Tất cả đường dẫn dưới đây tương đối so với base URL: https://sme-open-api-sandbox.tconnect.vn/openapi/v1/api-invoice

Mọi request cần 2 header xác thực: Authorization: Bearer <access_token> và Partner-Code: <mã Merchant>.

1. Đăng ký tài khoản cổng thuế

curl -X POST "$BASE/tax-accounts" \
  -H "Authorization: Bearer $TOKEN" -H "Partner-Code: $PC" \
  -H "Content-Type: application/json" \
  -d '{
    "mst": "0319074775",
    "password": "••••••••",
    "initialSync": { "dateFrom": "2026-07-01", "dateTo": "2026-07-31" }
  }'

{
  "id": "cf00eea0-af08-4e84-9aa3-e12d23b3a568",
  "maskedMst": "03•••••775",
  "status": "active",
  "initialJob": { "id": "b6bf6a2a-9082-4882-b798-b35fc5985894", "status": "queued" }
}

id chính là accountId dùng cho các bước sau. Mật khẩu cổng thuế được mã hóa ngay khi lưu.

2. Yêu cầu đồng bộ hóa đơn

curl -X POST "$BASE/tax-accounts/$ACC/sync" \
  -H "Authorization: Bearer $TOKEN" -H "Partner-Code: $PC" \
  -H "Content-Type: application/json" \
  -d '{ "dateFrom": "2026-07-01", "dateTo": "2026-07-31", "fetchDetails": true }'

{ "id": "b6bf6a2a-9082-4882-b798-b35fc5985894", "status": "queued", "priority": 0 }

fetchDetails: true → lấy cả dòng hàng của từng hóa đơn (chi tiết đầy đủ).
fetchDetails: false → chỉ lấy phần header (nhanh và rẻ hơn), dùng khi bạn chỉ cần danh sách tổng.
Khoảng ngày dài hơn 31 ngày sẽ tự động chia thành nhiều cửa sổ.

3. Theo dõi tiến trình

Poll đến khi status = succeeded:

curl "$BASE/sync-jobs/$JOB" -H "Authorization: Bearer $TOKEN" -H "Partner-Code: $PC"

{
  "id": "b6bf6a2a-9082-4882-b798-b35fc5985894",
  "status": "succeeded",
  "totalFound": 42,
  "totalSaved": 42
}

Các trạng thái: queued → running → succeeded | failed. Nếu failed, errorCode cho biết lý do — ví dụ INVALID_CREDENTIALS (sai mật khẩu, cần cập nhật) hoặc SYNC_FAILED (đồng bộ lỗi/mạng).

Gợi ý logic poll phía client:

function wait_for_sync(job_id):
    loop:
        job = GET /sync-jobs/{job_id}
        if job.status == "succeeded":
            return job
        if job.status == "failed":
            raise Error(job.errorCode, job.errorMessage)
        sleep(3 seconds)   // backoff nhẹ, tránh poll dồn dập

4. Lấy danh sách hóa đơn

Dữ liệu đã đồng bộ nằm trong hệ thống — truy vấn tức thì, có phân trang và lọc:

curl "$BASE/invoices?accountId=$ACC&direction=purchase&dateFrom=2026-07-01&dateTo=2026-07-31&page=1&limit=20&sort=issueDate:desc" \
  -H "Authorization: Bearer $TOKEN" -H "Partner-Code: $PC"

{
  "data": [
    {
      "id": "7b1e...c2",
      "sellerTaxCode": "0101243150",
      "sellerName": "CÔNG TY TNHH VẬT TƯ ABC",
      "buyerTaxCode": "0319074775",
      "invoiceSymbol": "C26TAB",
      "invoiceNumber": "205",
      "issueDate": "2026-07-18",
      "totalBeforeTax": 1472727,
      "totalTax": 147273,
      "totalAmount": 1620000,
      "currency": "VND"
    }
  ],
  "total": 42, "page": 1, "limit": 20, "totalPage": 3
}

Bạn có thể lọc theo sellerTaxCode, invoiceSymbol, invoiceNumber, issueDate — đây là các cột để nguyên bản (plaintext) phục vụ tìm kiếm.

5. Xem chi tiết + dòng hàng

curl "$BASE/invoices/$INV" -H "Authorization: Bearer $TOKEN" -H "Partner-Code: $PC"

{
  "id": "7b1e...c2",
  "invoiceSymbol": "C26TAB", "invoiceNumber": "205", "issueDate": "2026-07-18",
  "sellerName": "CÔNG TY TNHH VẬT TƯ ABC", "sellerTaxCode": "0101243150",
  "buyerName": "CÔNG TY CỔ PHẦN GIẢI PHÁP T CONNECT", "buyerTaxCode": "0319074775",
  "totalBeforeTax": 1472727, "totalTax": 147273, "totalAmount": 1620000, "currency": "VND",
  "taxBreakdown": [ { "taxRate": "10%", "amountBeforeTax": 1472727, "taxAmount": 147273 } ],
  "items": [
    {
      "lineNumber": 1, "description": "Mực in laser HP 12A", "unit": "Hộp",
      "quantity": 3, "unitPrice": 490909, "amount": 1472727,
      "taxRate": "10%", "taxAmount": 147273, "totalAmount": 1620000
    }
  ]
}

items chỉ có khi đồng bộ với fetchDetails=true, hoặc sau khi gọi POST /invoices/{id}/fetch-detail để lấy chi tiết đúng một hóa đơn theo yêu cầu.

Xác thực & bảo mật dữ liệu

Bộ API dùng chung cơ chế xác thực JWT Bearer (Keycloak) + Partner-Code với các Open API khác của TConnect (ví dụ API thanh toán). Về lưu trữ:

mã số thuế được băm HMAC-SHA256 — không lưu ở dạng thô.
Mật khẩu cổng thuế và các trường nhạy cảm (tên đối tác, số tiền, dòng hàng) được mã hóa AES-256-GCM.
Chỉ các cột phục vụ tìm kiếm (sellerTaxCode, buyerTaxCode, invoiceSymbol, invoiceNumber, issueDate) để nguyên bản.

Chỉ lấy hộ: hệ thống không sửa, không "làm sạch", không diễn giải lại dữ liệu. Con số bạn nhận đúng bằng con số trên cổng thuế.

Ứng dụng thực tế

Tự động hóa kế toán đầu vào: đồng bộ hóa đơn hằng tháng thẳng vào phần mềm kế toán, bỏ hẳn khâu tải tay.
Đối chiếu VAT: so khớp hóa đơn đầu vào với tờ khai thuế để phát hiện chênh lệch trước kỳ quyết toán.
Kiểm soát công nợ: đối chiếu hóa đơn nhận được với đơn đặt hàng/hợp đồng theo sellerTaxCode.
Cảnh báo hóa đơn mới: poll định kỳ, khi có hóa đơn mới thì đẩy thông báo cho kế toán.

Kết luận

API tra cứu hóa đơn đầu vào lấy hộ toàn bộ quy trình thủ công lặp đi lặp lại — đăng nhập cổng thuế, tải từng khoảng ngày — gói lại thành vài lời gọi API chạy nền. Dữ liệu về sạch, có cấu trúc, được mã hóa an toàn và giữ nguyên bản gốc từ Tổng cục Thuế.

Xem đặc tả đầy đủ tại tài liệu API tra cứu hóa đơn đầu vào — có sẵn file single-file để AI Agent tích hợp trực tiếp. Cần khóa sandbox để thử? Liên hệ TConnect.