# 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 {#basis}

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-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 {#history}

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ê](https://hatang.dev/vi/docs/guides/payments/bank-connections.md#statement-import). `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 {#key}

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](https://hatang.dev/vi/docs/guides/payments/environments.md).

## Các endpoint {#endpoints}

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

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

## Đồng bộ {#sync}

- **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](https://hatang.dev/vi/docs/guides/payments/webhooks.md) `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 {#rust}

[Crate `hatang`](https://hatang.dev/vi/docs/guides/sdks/rust.md) có sẵn các hàm có kiểu cho toàn bộ quy trình:

```rust
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](https://hatang.dev/vi/docs/reference/api.md) để biết từng trường.

Source: https://hatang.dev/vi/docs/guides/payments/revenue-api
