Bỏ qua điều hướng
monahđđtmột sản phẩm của MONA
Tra cứu hóa đơnDùng thử miễn phí
API hóa đơn điện tử

Kết nối một lần.
Theo dõi từng trạng thái.

API monahddt đang hoàn thiện và sẽ mở theo lộ trình sau khi kết nối hóa đơn, T-VAN và sandbox vượt kiểm thử. Tài liệu này mô tả luồng bất đồng bộ dự kiến, cấu trúc dữ liệu minh họa và cách theo dõi trạng thái; chưa công bố endpoint, khóa truy cập hoặc cam kết tương thích sản xuất.

Đang hoàn thiện — API mở theo lộ trình.

Chưa có endpoint công khai · chưa cấp khóa · chưa nhận dữ liệu sản xuất

Luồng bất đồng bộ

Create → check → issue → check → files → send.

Phát hành hóa đơn liên quan kiểm tra dữ liệu, ký, truyền nhận và phản hồi từ hệ thống bên ngoài. Client cần lưu mã tham chiếu, chống gửi lặp và xử lý nhiều trạng thái thay vì chờ một phản hồi tức thời.

  1. 01

    create

    Gửi dữ liệu giao dịch

    Ứng dụng gửi mã tham chiếu riêng, thông tin người bán, người mua, hàng hóa, thuế và tổng tiền. Khóa chống lặp đi cùng từng yêu cầu.

  2. 02

    check

    Kiểm tra đầu vào

    Hệ thống kiểm tra trường bắt buộc, định dạng, tổng tiền và quyền phát hành. Kết quả trả về trạng thái chờ, hợp lệ hoặc cần sửa.

  3. 03

    issue

    Yêu cầu phát hành

    Yêu cầu hợp lệ được đưa vào hàng đợi ký và chuyển theo luồng cơ quan thuế phù hợp. Đây là tác vụ bất đồng bộ, không nên giữ kết nối chờ lâu.

  4. 04

    check

    Theo dõi trạng thái phát hành

    Ứng dụng nhận webhook hoặc kiểm tra lại bằng mã tác vụ. Trạng thái cần phân biệt đang xử lý, thành công, bị từ chối và cần người dùng sửa.

  5. 05

    files

    Nhận PDF, XML và mã tra cứu

    Chỉ sau khi phát hành thành công, phản hồi mới có tham chiếu đến XML gốc, bản đọc PDF và mã hoặc đường dẫn tra cứu được phép công bố.

  6. 06

    send

    Gửi thông tin cho khách

    Ứng dụng gọi bước gửi hoặc để cấu hình tự gửi qua email, Zalo ZNS khi các kênh tương ứng đã được xác minh và kích hoạt.

Mẫu gọi API

PHP trước, rồi cURL và Node.

Các đoạn dưới minh họa cách giữ URL, đường dẫn và khóa ở biến môi trường. MONA chưa công bố giá trị thật. Sao chép lúc này sẽ không gửi được yêu cầu đến monahddt.

Quy ước: chuỗi trong dấu <...> và mọi biến MONAHDDT_* đều là placeholder.

PHP · cURL extension

MINH HỌA

cURL

MINH HỌA

Node · fetch

MINH HỌA
Request và response

Cấu trúc để thảo luận, chưa phải hợp đồng API.

Tên trường, kiểu dữ liệu, mã trạng thái và quy tắc thuế còn được chốt cùng lớp nghiệp vụ. Bản production sau này phải có version, changelog và OpenAPI khớp đúng hệ thống đang chạy.

Phản hồi minh họa

Tệp kết quả: fileslookup_code giữ giá trị rỗng cho đến khi tác vụ phát hành thành công. Ứng dụng không nên tự dựng đường dẫn PDF/XML.
Webhook

Xác minh chữ ký, chống lặp và trả phản hồi nhanh.

Tên event và header chữ ký chưa được công bố. Khi mở API, webhook sẽ đi kèm timestamp, mã giao sự kiện, chữ ký và hướng dẫn retry. Client lưu event ID trước khi chạy nghiệp vụ để một thông báo gửi lại không tạo thêm hóa đơn.

01

Xác minh nguồn gửi

Kiểm tra timestamp và chữ ký trên raw body bằng secret riêng của webhook.

02

Ghi nhận event ID

Lưu mã sự kiện trước khi cập nhật đơn để nhận lại cùng event mà không xử lý hai lần.

03

Trả HTTP nhanh

Đưa việc nặng vào hàng đợi nội bộ; cơ chế retry và mã phản hồi sẽ nằm trong tài liệu chính thức.

Sandbox

Chưa mở đăng ký sandbox.

Lộ trình dự kiến gồm đặc tả OpenAPI, dữ liệu test không chứa thông tin thật, khóa riêng theo môi trường, webhook inspector, bảng mã lỗi và giới hạn tần suất. Ngày mở, SLA, quota và chính sách versioning vẫn là TODO.

Có sơ đồ tích hợp rồi?

Gửi luồng create, check và webhook bạn đang cần.

MONA dùng sơ đồ thật để chốt hợp đồng API và thứ tự mở sandbox. Hiện tại chưa cấp endpoint, khóa hoặc nhận dữ liệu sản xuất.