Bản xem trước, API mở theo lộ trình
API hoá đơn điện tử, kết nối một lần rồi theo từng trạng thái
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 hoạ và cách theo dõi trạng thái. API sẽ mở sau khi kết nối nhà cung cấp hoá đơn, T-VAN và sandbox vượt kiểm thử.
Chưa có endpoint công khai, chưa cấp khoá và chưa nhận dữ liệu sản xuất.

Trạng thái tài liệu
- documentation_statuspreview
- Endpoint công khaiChưa có
- Khoá truy cậpChưa cấp
- Dữ liệu sản xuấtChưa nhận
Luồng bất đồng bộ
create → check → issue → check → files → send
Phát hành hoá đơ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.
createGử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 hoá, thuế và tổng tiền. Khoá chống lặp đi cùng từng yêu cầu.
checkKiểm tra đầu vàoHệ 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.
issueYêu cầu phát hànhYê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.
checkTheo 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.
filesNhận PDF, XML và mã tra cứuChỉ 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ố.
sendGử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 và 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 hoạ cách giữ URL, đường dẫn và khoá ở biến môi trường. Chuỗi trong dấu <...> và mọi biến MONAEINVOICE_* đều là placeholder, sao chép lúc này sẽ không gửi được yêu cầu nào.
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.
Trường files và lookup_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 hay 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ã 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 hoá đơn.
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.
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 một event mà không xử lý hai lần.
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, khoá 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 chưa được chốt. Nếu bạn đã có sơ đồ tích hợp, gửi luồng create, check và webhook đang cần — MONA dùng sơ đồ thật để chốt hợp đồng API và thứ tự mở sandbox. Trao đổi với đội tích hợp.
Muốn xem MONA viết SDK thế nào? Tổ chức github.com/themonagroup đang công khai thư viện và công cụ của các sản phẩm khác trong hệ, trong đó có SDK cổng thanh toán MONA Pay cho PHP, Node và Python. MONA eInvoice thì chưa có thư viện nào ở đó, vì lớp API thật còn đang chốt.

Bắt đầu với MONA eInvoice
Gửi sơ đồ tích hợp, MONA xếp thứ tự mở sandbox theo đó
Hiện chưa cấp endpoint, khoá hoặc nhận dữ liệu sản xuất. Đăng ký để nhận tin khi lớp API thật và sandbox được công bố.
- Sáu bướccreate · check · issue · check · files · send
- Idempotencykhoá chống lặp đi cùng từng yêu cầu
- Previewtrạng thái hiện tại của tài liệu này