API hoá đơn điện tử dành cho developer

Tích hợp hoá đơn điện tử vào phần mềm của bạn bằng một API.

Tạo, tra cứu và tải hoá đơn điện tử qua REST API thống nhất. hddt.dev kết nối nhà cung cấp hoá đơn và điều phối chữ ký số cùng quy trình gửi nhận kết quả, để đội ngũ của bạn tập trung vào sản phẩm.

REST API · JSON · Sandbox riêng · Gọi trực tiếp bằng HTTP

Vì sao dùng hddt.dev

Đừng xây dựng lại hạ tầng hoá đơn từ đầu.

Một lớp API thống nhất giúp nối quy trình hoá đơn điện tử vào phần mềm bán hàng, ERP, CRM hoặc nền tảng bạn đang xây.

Một API thống nhất

Tạo, tra cứu và tải hoá đơn qua REST và JSON, thay vì tự nối nhiều luồng với nhà cung cấp hoá đơn.

Sandbox tách khỏi Live

Kiểm thử bằng key và dữ liệu sandbox. Hoá đơn sandbox không được gửi cơ quan thuế.

Quản lý theo ứng dụng

Mỗi app có App ID, API key và môi trường riêng để tách sản phẩm, quyền truy cập và hạn mức.

Theo dõi kết quả xử lý

Đọc kết quả trên response, tra cứu danh sách hoá đơn, hoặc nhận webhook khi đã cấu hình.

Tích hợp

Từ API key đến hoá đơn đầu tiên trong vài bước.

Bắt đầu trong Sandbox, kiểm thử quy trình, rồi chuyển Live khi ứng dụng đã sẵn sàng.

  1. Bước 1

    Tạo tài khoản và ứng dụng

    Đăng ký hoặc đăng nhập bằng email, vào console và tạo app cho hệ thống cần tích hợp.

  2. Bước 2

    Lấy API key Sandbox

    App mới có sẵn key sandbox. Dùng key đó cùng App ID để lấy token và gọi API thử.

  3. Bước 3

    Gửi request và kiểm thử

    Lấy mẫu hoá đơn, tạo hoá đơn thử, đối chiếu response và các mã lỗi trên tài liệu.

  4. Bước 4Go-live

    Hoàn tất điều kiện Live

    Khai báo mã số thuế, tích hợp thử trên sandbox, rồi gửi yêu cầu bật Live. Key Live chỉ dùng sau khi được duyệt.

API

Một bộ API cho vòng đời hoá đơn điện tử.

Chọn endpoint theo việc cần làm.

Xem tài liệu API

Hoá đơn đầu ra

Chuẩn bị mẫu, tạo hoá đơn, xem danh sách và tải file.

Lấy danh sách mẫu hoá đơn

Đang hỗ trợ

Mẫu số và ký hiệu đã đăng ký, chọn khi tạo hoá đơn.

GET/v1/invoices/templates
Xem tài liệu

Tạo hoá đơn

Đang hỗ trợ

Lưu nháp hoặc tạo và phát hành, tuỳ issue_mode.

POST/v1/invoices
Xem tài liệu

Danh sách hoá đơn

Đang hỗ trợ

Lọc theo mẫu, ngày lập, số hoá đơn, loại và trạng thái.

GET/v1/invoices
Xem tài liệu

Tải hoá đơn

Đang hỗ trợ

Tải PDF để gửi khách hoặc XML để lưu trữ, đối soát.

GET/v1/invoices/{id}/download
Xem tài liệu

Dữ liệu hỗ trợ

Điền thông tin người mua trước khi tạo hoá đơn.

Tra cứu mã số thuế

Đang hỗ trợ

Lấy tên, địa chỉ và trạng thái hoạt động từ mã số thuế.

GET/v1/tax-codes/{mst}
Xem tài liệu

Ví dụ

Tạo hoá đơn bằng một HTTP request.

Gửi dữ liệu người mua và hàng hoá. API trả mã hoá đơn để bạn lưu và theo dõi tiếp. Đây là ví dụ rút gọn, không đủ cho mọi loại hoá đơn.

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" \
  -d '{
    "issue_mode": 0,
    "invoice_type": 0,
    "template_id": "1C26TAA",
    "currency": "VND",
    "exchange_rate": 1,
    "buyer": {
      "tax_code": "0312345678",
      "name": "Công ty TNHH ABC"
    },
    "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
  }'

Response minh hoạ

success là kết quả tạo hoá đơn trên môi trường đang gọi.

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "number": 125,
    "lookup_code": "ABC123"
  },
  "error_code": "",
  "message": "Thành công"
}

Ví dụ lưu nháp trên Sandbox với issue_mode bằng 0. Phát hành dùng issue_mode bằng 1. Token lấy từ POST /v1/invoices/token, rồi gửi kèm api_key và app_id. Một số API khác, như tra cứu mã số thuế, dùng Authorization Bearer với chính API key.

Luồng xử lý

Theo dõi cả quy trình, không chỉ kết quả HTTP.

Các bước dưới đây là cách hệ thống điều phối. Không phải bước nào cũng xong ngay trong cùng một response.

  1. 01

    Ứng dụng gửi request

    Hệ thống của bạn gọi API với token, API key và App ID cùng môi trường.

  2. 02

    Kiểm tra dữ liệu

    hddt.dev kiểm tra xác thực, định dạng và các trường bắt buộc trước khi tạo.

  3. 03

    Lập hoá đơn và ký số

    Nền tảng điều phối lập hoá đơn và ký số theo cấu hình của ứng dụng.

  4. 04

    Gửi theo môi trường

    Live đi theo quy trình phát hành. Sandbox dừng ở dữ liệu thử, không gửi cơ quan thuế.

  5. 05

    Cập nhật kết quả

    Mã hoá đơn, số hoá đơn và mã tra cứu trả về để bạn lưu và đối soát.

  6. 06

    Tra cứu hoặc webhook

    Đọc lại trạng thái bằng API, hoặc nhận sự kiện nếu webhook của app đang bật.

Developer Console

Mỗi sản phẩm, một ứng dụng riêng.

Quản lý thông tin kết nối, API key, chữ ký số và nhật ký request theo từng ứng dụng.

  • Tạo và quản lý nhiều ứng dụng trong một tài khoản.
  • Sandbox và Live tách host, key, hạn mức và nhật ký.
  • Tạo, xem có che và thu hồi API key theo môi trường.
  • Xem chứng thư số khi tài khoản nhà cung cấp đã được gắn.
  • Đăng ký webhook và giới hạn IP trên từng môi trường.
  • Xem hạn mức còn lại và nhật ký request khi API đã ghi log.
Mở Developer Console
hddt.dev/apps · minh hoạ

Ứng dụng

Shop demo

Sandbox

API key

hddt_test_4f9c••••••••••a21e
  • Công ty TNHH ABC

    5.500.000 ₫

    Nháp
  • Cửa hàng demo

    1.210.000 ₫

    Đang xử lý

Dữ liệu minh hoạ. Key được che.

Use case

Bổ sung hoá đơn vào sản phẩm bạn đang xây.

Bạn vẫn dựng workflow trong phần mềm của mình. hddt.dev cung cấp API để gọi tại bước lập và theo dõi hoá đơn.

Phần mềm bán hàng / POS

Có thể gọi API tạo hoá đơn từ đơn hàng sau khi thanh toán hoặc hoàn tất giao dịch.

ERP / CRM

Có thể nối dữ liệu khách hàng và đơn hàng sang hoá đơn trong quy trình bạn đang vận hành.

Nền tảng SaaS

Mỗi doanh nghiệp dùng phần mềm của bạn có thể gắn với một ứng dụng và bộ key riêng.

Thương mại điện tử

Có thể lập hoá đơn từ đơn hàng và đồng bộ mã tra cứu, số hoá đơn về hệ thống quản lý.

Vận hành

Kiểm soát kết nối và dữ liệu ở từng ứng dụng.

Những khả năng dưới đây đang có trên console và API. Tuân thủ hoá đơn còn phụ thuộc dữ liệu đầu vào, chứng thư số và quy định hiện hành.

Key theo app và môi trường

Key sandbox có tiền tố riêng. Key Live không dùng lẫn với host sandbox.

Thu hồi key

Thu hồi trên console khi key lộ. Key đã thu hồi không gọi được API.

HTTPS

Request tới API đi qua HTTPS. Webhook đăng ký bằng URL HTTPS.

Giới hạn IP

Có thể khai báo dải IP được phép gọi API cho từng môi trường của app.

Nhật ký request

Console đọc nhật ký theo môi trường đang xem khi API đã ghi log.

Chữ ký số

Tab Chữ ký số hiện chứng thư đang khai báo. Kết quả phát hành còn phụ thuộc chứng thư, dữ liệu và quy trình áp dụng.

Chi phí

Chi phí tách theo việc bạn dùng.

Sandbox để kiểm thử. Live tính theo hạn mức hoá đơn. Chữ ký số là gói riêng.

Xem bảng giá

Sandbox

Dùng để kiểm thử tích hợp. Hoá đơn tạo trên sandbox không gửi cơ quan thuế.

Hạn mức Live

Phí phát hành tính theo gói hạn mức hoá đơn trên môi trường Live. Chi tiết từng bậc nằm ở trang bảng giá.

Chữ ký số

Gói chữ ký số tính riêng, không gộp vào hạn mức hoá đơn. Xem cùng trang bảng giá.

Hỏi đáp

Trước khi gửi request đầu tiên.

Sandbox có phát hành hoá đơn có giá trị pháp lý không?

Không. Hoá đơn tạo bằng key và host sandbox không được gửi cơ quan thuế. Dùng Live sau khi ứng dụng được duyệt để phát hành hoá đơn thật.

Làm thế nào để chuyển từ Sandbox sang Live?

Trên tổng quan ứng dụng, hoàn tất tích hợp thử trên sandbox và khai báo mã số thuế ở Cài đặt hoá đơn. Đủ điều kiện thì gửi yêu cầu chuyển Live. Đội hỗ trợ xác minh rồi mới bật Live. Sau đó dùng host và API key của Live, không dùng lại key sandbox.

Tôi cần chuẩn bị thông tin doanh nghiệp và chữ ký số thế nào?

Khai báo mã số thuế và tên đơn vị ở tab Cài đặt hoá đơn. Chứng thư số hiện ở tab Chữ ký số khi tài khoản nhà cung cấp đã được gắn với app. Việc chọn hoặc đăng ký chứng thư mới trên tab hiện chưa được lưu.

API hỗ trợ những ngôn ngữ nào?

Mọi ngôn ngữ gửi được HTTP. Trang này có ví dụ cURL, Node.js, Python và PHP bằng HTTP thuần. Không cần cài SDK để gọi API.

API key có tách theo từng ứng dụng không?

Có. Mỗi ứng dụng có App ID và API key riêng cho Sandbox và cho Live. Thu hồi key trên tab Kết nối và bảo mật của đúng môi trường.

Request bị timeout thì hoá đơn đã được tạo chưa?

Không kết luận chỉ từ timeout. Khi tạo hoá đơn có thể gửi header Idempotency-Key. Gửi lại cùng key và cùng nội dung để nhận lại kết quả đã tạo. Cùng key nhưng nội dung khác trả 409. Bạn cũng có thể tra cứu lại bằng API danh sách hoá đơn.

success: true có nghĩa cơ quan thuế đã chấp nhận hoá đơn không?

Không. success cho biết request tạo được hoá đơn trên môi trường đang gọi và trả id (UUID), number, lookup_code. Trạng thái với cơ quan thuế cần tra cứu tiếp hoặc nhận webhook, nếu bạn đã đăng ký.

Có tải được PDF và XML không?

Có endpoint tải hoá đơn để lấy PDF hoặc XML. Cách gọi và tham số nằm trong tài liệu API.

Webhook có những sự kiện nào?

Đăng ký được các sự kiện: tất cả, tạo mẫu hoá đơn, duyệt số lượng mẫu hoá đơn, xoá mẫu hoá đơn, tạo nháp hoá đơn, phát hành hoá đơn, ký hoá đơn, CQT phản hồi, và xoá hoá đơn nháp. Bí mật ký chỉ trả một lần lúc tạo webhook. Thông báo là JSON. Chữ ký là HMAC-SHA256 của nguyên văn body. URL được chờ tối đa 3 giây và không được gửi lại nếu lỗi.

Sẵn sàng đưa hoá đơn điện tử vào sản phẩm của bạn?

Tạo tài khoản, khởi tạo ứng dụng và thử API trong Sandbox trước khi kết nối Live.