Chuyển tới nội dung chính

Revenue API

Revenue API cho phép doanh nghiệp chia sẻ doanh thu đã xác minh: số tiền thực sự về tài khoản ngân hàng. Một site bên thứ ba nhận một key chỉ đọc và đọc số liệu này, giống cách dùng key của Stripe hay Polar. Ví dụ: bảng xếp hạng kiểu TrustMRR, nhà đầu tư, sàn mua bán startup.

Site nhận được ba thứ:

  • Key thuộc về ai. Kèm theo cho biết key chỉ đọc hay không.
  • Từng khoản tiền đã nhận, cũ nhất trước, xa nhất mà lịch sử có.
  • Tổng theo ngày hoặc tháng. Trong đó có 30 ngày gần nhất, là con số các bảng xếp hạng dùng khi không có MRR từ gói thuê bao.

Thế nào là doanh thu​

Chọn basis ở mỗi lần gọi:

basisTính những gìThời điểm
bankMọi khoản chuyển vào các tài khoản ngân hàng đã liên kết, trừ khoản đã đánh dấu không phải doanh thuLúc ngân hàng ghi nhận (booked_at)
payments (mặc định)Các thanh toán VietQR của Hạ Tầng đã trả, theo số tiền thực nhận (paid_amount)Lúc paid_at

bank là con số rộng nhất. Nó tính tiền từ mọi nguồn: thanh toán VietQR, khách chuyển khoản thẳng, tiền sàn thương mại điện tử trả về. payments hẹp hơn: chỉ các thanh toán tạo qua Hạ Tầng.

Không basis nào tính:

  • Tiền chuyển ra.
  • Khoản đã đánh dấu không phải doanh thu, như tiền hoàn lại, chuyển giữa các tài khoản của chính bạn, hay khoản vay. Đánh dấu trong dashboard (Thanh toán → Đối soát hoá đơn → khoản chuyển → Không cần hoá đơn), hoặc gọi POST /payments/transactions/{id}/invoice-exempt kèm lý do. Đây là cùng một cờ mà đối soát hoá đơn điện tử dùng; bỏ đánh dấu bằng DELETE trên cùng đường dẫn.
  • Gói thuê bao App Store, Google Play và web ghi trong CRM hỗ trợ. Chỉ tiền thấy ở phía ngân hàng mới được tính.

Số tiền là đồng chẵn (VND, không có đơn vị lẻ). Tiền hoàn trả cho khách chưa được nối với khoản thu ban đầu, nên chưa bị trừ.

Lịch sử xa tới đâu​

Lịch sử của bank bắt đầu từ khoản chuyển cũ nhất mà Hạ Tầng có cho tài khoản đó:

  • những gì ngân hàng gửi từ lúc liên kết;
  • phần lịch sử Hạ Tầng đọc lại từ ngân hàng;
  • mọi sao kê bạn nhập vào.

Muốn đưa thêm các tháng cũ hơn, nhập sao kê. GET /revenue/summary trả totals.first_at, là khoản tiền cũ nhất đang có, để site hiển thị được bao nhiêu lịch sử đã xác minh.

Key chỉ đọc​

Tạo API key chỉ có payments:read: API keys → Tạo → Payments: Read. Key này đọc được thanh toán, giao dịch và doanh thu, không sửa được gì.

GET /revenue/account trả read_only: true cho key như vậy. Site nên từ chối key có read_only: false, giống cách TrustMRR từ chối secret key của Stripe.

Key tạo trong dashboard đọc dữ liệu production. Key development (ht_test_…) đọc môi trường development; xem Môi trường.

Các endpoint​

MethodĐường dẫnTrả về
GET/revenue/accountDoanh nghiệp, các tài khoản ngân hàng đã liên kết (che số), scope của key và read_only
GET/revenue/eventsCác khoản đã nhận, cũ nhất trước: basis, since, until, limit (≤ 500), after
GET/revenue/summaryTổng theo interval (day hoặc month) từ from đến to trong tz (mặc định Asia/Ho_Chi_Minh), kèm tổng toàn thời gian, 30 ngày gần nhất và 30 ngày trước đó

/payments và /payments/transactions cũng nhận bộ lọc ngày: created_after / created_before / paid_after / paid_before, và booked_after / booked_before.

curl "https://api.hatang.dev/revenue/events?basis=bank&since=2025-01-01&limit=500" \
-H "Authorization: Bearer ht_…"

Đồng bộ​

  • Lần đầu. Gọi GET /revenue/events không có since (hoặc với ngày cũ nhất bạn cần) và đi theo next_cursor cho tới khi has_more là false.
  • Các lần sau. Gọi lại với since lùi vài ngày so với occurred_at cuối cùng bạn đã lưu, và loại trùng theo id. id cố định: là id giao dịch với bank, id thanh toán với payments. Sao kê có thể thêm khoản cũ bất cứ lúc nào, nên thỉnh thoảng đọc lại một khoảng rộng hơn.
  • Cho con số trên bảng xếp hạng, GET /revenue/summary có sẵn totals.last_30_days và previous_30_days, không cần phân trang.
  • Để nhận tiền mới ngay khi về, đăng ký webhook transaction.received và payment.succeeded. Quản lý webhook cần key có quyền ghi, nên doanh nghiệp tự cài.

Với SDK Rust​

Crate hatang có sẵn các hàm có kiểu cho toàn bộ quy trình:

use hatang::{Hatang, RevenueBasis};

let hatang = Hatang::new(key_doanh_nghiep_gui_cho_ban)?;
let account = hatang.revenue.account().await?;
if !account.read_only {
return Err("hãy dùng key chỉ có payments:read".into());
}
let events = hatang.revenue.events_since(RevenueBasis::Bank, Some("2025-01-01")).await?; // tự đi theo cursor
let summary = hatang.revenue.summary(&Default::default()).await?;
println!("{}: {} đ trong 30 ngày gần nhất", account.business.name, summary.totals.last_30_days);

Với ngôn ngữ khác, gọi trực tiếp các endpoint ở trên. Xem REST API để biết từng trường.

Xem trang này dạng Markdown