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:
basis | Tính những gì | Thời điểm |
|---|---|---|
bank | Mọ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 thu | Lú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-exemptkè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ằngDELETEtrê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ẫn | Trả về |
|---|---|---|
GET | /revenue/account | Doanh 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/events | Các khoản đã nhận, cũ nhất trước: basis, since, until, limit (≤ 500), after |
GET | /revenue/summary | Tổ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/eventskhông cósince(hoặc với ngày cũ nhất bạn cần) và đi theonext_cursorcho tới khihas_morelà false. - Các lần sau. Gọi lại với
sincelùi vài ngày so vớioccurred_atcuối cùng bạn đã lưu, và loại trùng theoid.idcố định: là id giao dịch vớibank, id thanh toán vớipayments. 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/summarycó sẵntotals.last_30_daysvàprevious_30_days, không cần phân trang. - Để nhận tiền mới ngay khi về, đăng ký webhook
transaction.receivedvà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.