API tra cứu giao dịch ngân hàng - Truy xuất dữ liệu mọi lúc mọi nơi

Ngoài webhook realtime, ThueAPI.VN cung cấp REST API cho phép bạn chủ động tra cứu lịch sử giao dịch, lọc dữ liệu và phân tích thanh toán. Bài viết này hướng dẫn cách sử dụng từng endpoint.

Cách truy cập tạo và quản lý API tài khoản: Dashboard → API Keys. 

Xác thực API

Mọi request đều yêu cầu API Key trong header:

GET /api/v1/transactions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

API key được tạo và quản lý tại Dashboard → API Keys.

Danh sách giao dịch

GET /api/v1/transactions

Query parameters:

Param Kiểu Mô tả
page Integer Trang hiện tại (mặc định: 1)
per_page Integer Số giao dịch/trang (tối đa: 100)
bank String Lọc theo ngân hàng (VCB, ACB...)
type String Lọc theo loại: IN (nhận), OUT (chuyển đi)
from_date Date Từ ngày (Y-m-d)
to_date Date Đến ngày (Y-m-d)

Response mẫu:

{
  "status": true,
  "messages": "Thành công",
  "transactions": [
    {
      "id": 1234,
      "transaction_date": "2026-03-20 14:30:00",
      "transaction_id": "FT263079VN",
      "account_number": "0123456789",
      "bank": "VCB",
      "amount": 500000,
      "description": "THANH TOAN DON HANG 12345",
      "type": "IN",
      "checksum": "abc123..."
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 48,
    "per_page": 10
  }
}

Danh sách tài khoản ngân hàng

GET /api/v1/bank-accounts

Trả về danh sách tài khoản ngân hàng đã kết nối, bao gồm trạng thái hoạt động, loại kết nối và ngân hàng.

Quản lý Webhook qua API

GET    /api/v1/webhooks          # Danh sách webhook
POST   /api/v1/webhooks          # Tạo webhook mới
PATCH  /api/v1/webhooks/{id}     # Cập nhật webhook
DELETE /api/v1/webhooks/{id}     # Xóa webhook

Phân tích dữ liệu giao dịch

GET /api/v1/analytics/summary     # Tổng quan giao dịch
GET /api/v1/analytics/daily        # Thống kê theo ngày
GET /api/v1/analytics/by-bank      # Thống kê theo ngân hàng

Các endpoint phân tích giúp bạn nắm bắt nhanh:

  • Tổng số giao dịch và tổng tiền trong khoảng thời gian
  • Phân bổ giao dịch theo ngân hàng
  • Xu hướng giao dịch theo ngày/tuần/tháng

Rate Limiting

API giới hạn 60 request/phút cho mỗi API key. Khi vượt quá, bạn nhận HTTP 429:

{
  "status": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Mẹo: Sử dụng webhook thay vì polling liên tục để giảm số lượng API call và nhận dữ liệu nhanh hơn.

Xử lý lỗi thường gặp

HTTP Code Nguyên nhân Cách xử lý
401 API key không hợp lệ hoặc hết hạn Kiểm tra lại API key
403 Tài khoản bị khóa Liên hệ hỗ trợ
404 Endpoint không tồn tại Kiểm tra URL
429 Vượt quá rate limit Chờ theo retry_after
500 Lỗi server Thử lại sau hoặc liên hệ hỗ trợ