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.

Ba nguồn dữ liệu gọi về một luồng, mỗi bước trả một trạng thái đọc được.
  1. 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 hoá, thuế và tổng tiền. Khoá chống lặp đi cùng từng yêu cầu.

  2. 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. 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. 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. 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. 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 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.

PHP · cURL extension — minh hoạ
<?php
$baseUrl    = getenv('MONAEINVOICE_API_BASE_URL');
$createPath = getenv('MONAEINVOICE_CREATE_PATH');
$apiKey     = getenv('MONAEINVOICE_API_KEY');
// Các biến trên chỉ được cấp khi API mở; chưa có endpoint công khai.

$payload = [
    'client_reference' => 'ORDER-0246',
    'seller_tax_id'    => '<MST_NGUOI_BAN>',
    'buyer'            => ['name' => 'Công ty mẫu', 'tax_id' => '<MST_NGUOI_MUA>'],
    'items'            => [[
        'name'       => 'Dịch vụ tháng 09/2026',
        'quantity'   => 1,
        'unit_price' => 1000000,
        'tax_rate'   => '<THUE_SUAT_DA_DOI_CHIEU>',
    ]],
];

$request = curl_init(rtrim($baseUrl, '/') . '/' . ltrim($createPath, '/'));
curl_setopt_array($request, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: order-0246-invoice-v1',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($request);
cURL — minh hoạ
# Chỉ chạy sau khi MONA cấp URL, đường dẫn và khoá sandbox thật.
curl --request POST "${MONAEINVOICE_API_BASE_URL}/${MONAEINVOICE_CREATE_PATH}" \
  --header "Authorization: Bearer ${MONAEINVOICE_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-0246-invoice-v1" \
  --data @invoice-request.json
Node · fetch — minh hoạ
const baseUrl    = process.env.MONAEINVOICE_API_BASE_URL;
const createPath = process.env.MONAEINVOICE_CREATE_PATH;
const apiKey     = process.env.MONAEINVOICE_API_KEY;
// URL và đường dẫn chỉ có giá trị sau khi API được công bố.

const response = await fetch(baseUrl.replace(/\/$/, '') + '/' + createPath.replace(/^\//, ''), {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-0246-invoice-v1',
  },
  body: JSON.stringify({
    client_reference: 'ORDER-0246',
    seller_tax_id: '<MST_NGUOI_BAN>',
    buyer: { name: 'Công ty mẫu', tax_id: '<MST_NGUOI_MUA>' },
    items: [{
      name: 'Dịch vụ tháng 09/2026',
      quantity: 1,
      unit_price: 1000000,
      tax_rate: '<THUE_SUAT_DA_DOI_CHIEU>',
    }],
  }),
});

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.

Phản hồi minh hoạ
{
  "documentation_status": "example_only",
  "job_reference": "<DO_MONAEINVOICE_TRA_KHI_API_MO>",
  "client_reference": "ORDER-0246",
  "status": "<TRANG_THAI_TRONG_HOP_DONG_API_TUONG_LAI>",
  "next_action": "<CHO_KIEM_TRA_HOAC_CHO_PHAT_HANH>",
  "files": null,
  "lookup_code": null
}

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.

  1. 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.

  2. 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.

  3. 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