hddt.dev
Tài liệuBảng giáTra cứu

Bắt đầu

  • Tổng quan
  • Bắt đầu nhanh
  • Xác thực
  • Môi trường sandbox
  • Mã lỗi

Ứng dụng

  • GETThông tin ứng dụng
  • PATCHCập nhật ứng dụng

Hoá đơn

  • POSTLấy token
  • GETLấy mẫu hoá đơn
  • GETDanh sách mẫu đã đăng ký
  • GETHạn mức hoá đơn
  • POSTTạo mẫu hoá đơn
  • POSTDuyệt số lượng hoá đơn
  • DELETEXoá mẫu chưa duyệt
  • POSTTạo hoá đơn
  • GETDanh sách hoá đơn
  • POSTKý hoá đơn nháp
  • GETTải hoá đơn PDF/XML
  • DELETEXoá hoá đơn nháp

Tra cứu

  • GETTra cứu mã số thuế

Webhook

  • GETDanh sách webhook
  • POSTThêm webhook
  • POSTNhận và kiểm tra
Trang chủTài liệuBắt đầu nhanh

Bắt đầu nhanh

Tạo ứng dụng, lấy token sandbox và phát hành một hoá đơn thử. Hoá đơn sandbox không gửi tới cơ quan thuế.

Markdown

#Giới thiệu

Làm trên Sandbox trước. Host là https://sandbox.api.hddt.dev. API key có tiền tố hddt_test_. Hoá đơn tạo ở đây không được gửi cơ quan thuế.

Ba giá trị đi cùng nhau trên mọi API hoá đơn: API key, App ID và token. Token lấy từ API Lấy token, hết hạn sau khoảng 1 giờ.

#Chuẩn bị

Đăng nhập, tạo một ứng dụng. Ứng dụng mới mở ở Sandbox và đã có API key sandbox. Mở tab Kết nối & bảo mật, chọn Sandbox, rồi sao chép Base URL, App ID và API key.

Lấy token chỉ cần gửi App ID trên header cùng API key. Hệ thống tự lấy mã số thuế và tài khoản nhà cung cấp đã gắn với ứng dụng. Đội hỗ trợ gắn tài khoản trên trang quản trị. Chưa có tài khoản thì API Lấy token trả 401.

Chỉ gọi từ server

Không đưa API key, App ID hay token vào trình duyệt, ứng dụng mobile hoặc Git.

#Lấy token

Gửi POST /v1/invoices/token. Header api_key và app_id phải cùng một ứng dụng. Không có body. Không gửi username hay password.

cURL
curl -X POST https://sandbox.api.hddt.dev/v1/invoices/token \
  -H "api_key: $HDDT_API_KEY" \
  -H "app_id: $HDDT_APP_ID"

Giữ token

Phản hồi có token, token_type Bearer và expires_at. Dùng đến expires_at. Hết hạn hoặc khi API hoá đơn trả 401 thì gọi lại endpoint này.

#Lấy mẫu

Gửi GET /v1/invoices/templates với năm trên query. Header Authorization mang token vừa lấy. Gửi kèm api_key và app_id. Lấy id của một mẫu để điền template_id lúc tạo hoá đơn. Chưa có mẫu trong năm đó thì data là mảng rỗng. Tạo mẫu bằng API Tạo mẫu hoá đơn.

cURL
curl "https://sandbox.api.hddt.dev/v1/invoices/templates?year=2026" \
  -H "Authorization: Bearer $HDDT_TOKEN" \
  -H "api_key: $HDDT_API_KEY" \
  -H "app_id: $HDDT_APP_ID"

#Tạo hoá đơn

Gửi POST /v1/invoices. issue_mode bằng 1 là tạo và phát hành. invoice_type bằng 0 là hoá đơn mới. currency gửi VND thì exchange_rate là 1. Đủ trường bắt buộc của dòng hàng nằm ở trang Tạo hoá đơn.

Khi thành công, success là true. data.id là UUID của hoá đơn, data.number là số hoá đơn, data.lookup_code là mã tra cứu.

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 '{
    "issue_mode": 1,
    "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
  }'

Sandbox không ra cơ quan thuế

Hoá đơn sandbox không được gửi cơ quan thuế và trừ vào sổ hạn mức thử. Phát hành thật dùng host https://api.hddt.dev với API key tiền tố hddt_live_ sau khi Live được duyệt.

#Tiếp theo

Đọc Xác thực để chọn đúng header cho từng API. Đọc Môi trường sandbox trước khi gọi Live. Danh sách đủ trường nằm ở trang Tạo hoá đơn. Muốn nhận kết quả sau khi phát hành, thêm webhook rồi xem trang Nhận và kiểm tra.

Trước đóTổng quanTiếp theoXác thực
Trang này có hữu ích không?
Cập nhật lần cuối: 16/11/2026

Trên trang này

  • Giới thiệu
  • Chuẩn bị
  • Lấy token
  • Lấy mẫu
  • Tạo hoá đơn
  • Tiếp theo
Đăng nhậpBắt đầu ngay