API v1 · Cập nhật 26/10/2026

Tài liệu API hddt.dev

hddt.dev cung cấp REST API để phát hành, quản lý và tra cứu hoá đơn điện tử theo Nghị định 123/2020/NĐ-CP và Thông tư 78/2021/TT-BTC. Mọi request và phản hồi đều dùng JSON.

Bản cho AI, chỉ gồm API đã có trang tài liệu: llms.txt · llms-full.txt · openapi.json

Base URL

Mọi endpoint đều có tiền tố phiên bản. Dùng môi trường sandbox để thử nghiệm — hoá đơn tạo trên sandbox không được gửi tới cơ quan thuế.

Productionhttps://api.hddt.dev/v1
Sandboxhttps://sandbox.api.hddt.dev/v1

Xác thực

Tạo API key trong trang quản trị. API ứng dụng và Lấy token gửi key trong header api_key. Các API hoá đơn, sau khi lấy token, gửi token trong Authorization và API key trong header api_key. Tra cứuMST vẫn dùng Authorization: Bearer với API key. Key sandbox có tiền tố hddt_test_, key Live có tiền tố hddt_live_.

Terminal
curl https://sandbox.api.hddt.dev/v1/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "api_key: $HDDT_API_KEY"

Giữ bí mật API key

Không đưa API key vào mã nguồn phía client hoặc commit lên Git. Nếu key bị lộ, hãy thu hồi ngay trong trang quản trị.

Request đầu tiên

POST/v1/invoices

Ví dụ dưới đây phát hành một hoá đơn trên Sandbox. Header Authorization mang token từ API Lấy token. Header api_key và app_id mang API key và App ID của cùng ứng dụng, cùng môi trường với token.

cURL
curl -X POST https://sandbox.api.hddt.dev/v1/invoices \
  -H "Authorization: Bearer $HDDT_TOKEN" \
  -H "api_key: $HDDT_API_KEY" \
  -H "app_id: $HDDT_APP_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1d6c3e-2f4b-4a8e" \
  -d '{
    "invoice_type": 0,
    "template_id": "1C26TAA",
    "currency": "VND",
    "exchange_rate": 1,
    "items": [
      {
        "item_type": 1,
        "line_number": 1,
        "name": "Gói phần mềm",
        "quantity": 1,
        "unit_price": 5000000,
        "amount_before_discount": 5000000,
        "discount_rate": 0,
        "discount_amount": 0,
        "amount": 5000000,
        "vat_rate": 10,
        "tax_amount": 500000,
        "line_total": 5500000
      }
    ],
    "subtotal": 5000000,
    "trade_discount": 0,
    "other_deduction": 0,
    "tax_total": 500000,
    "total": 5500000
  }'

Body

invoice_typeintegerBắt buộc

Tính chất hoá đơn. 0 là hoá đơn mới.

template_idstringTuỳ chọn

Mã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA.

currencystringBắt buộc

Mã tiền tệ ISO 4217. VND là Việt Nam đồng.

exchange_ratenumberBắt buộc

Tỷ giá. Với VND gửi 1.

subtotalnumberBắt buộc

Tổng tiền trước thuế.

trade_discountnumberBắt buộc

Tổng chiết khấu thương mại. Gửi 0 nếu không có.

other_deductionnumberBắt buộc

Tổng giảm trừ khác. Gửi 0 nếu không có.

tax_totalnumberBắt buộc

Tổng tiền thuế.

totalnumberBắt buộc

Tổng tiền thanh toán.

itemsarrayBắt buộc

Dòng hàng. Mỗi dòng bắt buộc có item_type, line_number, name, quantity, unit_price, amount_before_discount, discount_rate, discount_amount, amount, vat_rate, tax_amount, line_total.

Phản hồi

Khi thành công, success là true. data chứa mã hoá đơn, số hoá đơn và mã tra cứu. Danh sách đủ trường bắt buộc nằm ở trang Tạo hoá đơn.

Phản hồi
{
  "success": true,
  "data": {
    "invoice_code": "inv_8f2a1c9d",
    "number": 125,
    "lookup_code": "ABC123"
  },
  "error_code": "",
  "message": "Thành công"
}

Mẹo

Gửi kèm header Idempotency-Key để tránh phát hành trùng hoá đơn khi request bị retry do lỗi mạng.

Mã lỗi

hddt.dev dùng mã trạng thái HTTP chuẩn. Phần thân lỗi luôn có error.code và error.message.

HTTPMã lỗiMô tả
400bad_requestRequest sai định dạng hoặc thiếu tham số bắt buộc.
401unauthorizedAPI key hoặc token không hợp lệ. API hoá đơn còn từ chối khi thiếu header api_key hoặc key không cùng ứng dụng với token.
404not_foundKhông tìm thấy tài nguyên được yêu cầu.
409conflictTrùng Idempotency-Key với request khác nội dung.
422validation_errorDữ liệu không hợp lệ theo quy định của CQT.
429rate_limitedVượt giới hạn số request cho phép.

Bước tiếp theo

Trang này có hữu ích không?
Cập nhật lần cuối: 26/10/2026