GVI — API Roadmap & Kế Hoạch Phát Triển

RESTful API Mapping · Admin Dashboard · docx.goldvninvest.online

Phiên bản 1.0.0 2026-07-20 DB: v5 Base: /api/v1/admin/ goldvninvest.online

1. User & Compliance 2. Finance & Trading 3. Orders & Transactions 4. Extensions 5. Lộ trình tài liệu 6. API Standards 7. Checklist

📊 Tổng Quan Tiến Độ

Module 1 — User & Compliance11/11 endpoints

Module 2 — Finance & Trading18/22 endpoints (4 Phase 3 pending)

Module 3 — Orders & Transactions12/12 endpoints

Module 4 — Extensions21/21 active (staking_pools data pending)

Tài liệu docx.goldvninvest.online6/16 docs (10 TODO)

1. User & Compliance Management

Base prefix: /api/v1/admin/

1.1 Users & Roles

Method	Endpoint	Mô tả	Auth	Status
GET	`/users`	Danh sách user (filter, paginate)	Admin	✅ Live
GET	`/users/:id`	Chi tiết 1 người dùng	Admin	✅ Live
PUT	`/users/:id`	Cập nhật thông tin user	Admin	✅ Live
DEL	`/users/:id`	Xóa / vô hiệu hóa user	SuperAdmin	✅ Live
GET	`/users/export`	Xuất danh sách CSV	Admin	✅ Live
GET	`/users/:id/activity`	Lịch sử hoạt động user	Admin	✅ Live
GET	`/roles`	Danh sách vai trò	Admin	✅ Live
POST	`/roles`	Tạo vai trò mới	SuperAdmin	✅ Live
PUT	`/roles/:id`	Cập nhật vai trò & permissions	SuperAdmin	✅ Live
DEL	`/roles/:id`	Xóa vai trò	SuperAdmin	✅ Live
GET	`/permissions`	Danh sách 625 quyền hệ thống	SuperAdmin	✅ Live

1.2 KYC & Compliance

Trạng thái: kyc_level = 0 records → cần seed Level 1 (CCCD) & Level 2 (C06+Liveness). Xem Phase 3 Playbook.

Method	Endpoint	Mô tả	Auth	Status
GET	`/kyc/applications`	Danh sách hồ sơ KYC	Admin	✅ Live
GET	`/kyc/applications/:id`	Chi tiết 1 hồ sơ KYC	Admin	✅ Live
PUT	`/kyc/applications/:id`	Duyệt / từ chối KYC	Admin	✅ Live
DEL	`/kyc/applications/:id`	Xóa hồ sơ KYC	SuperAdmin	✅ Live
GET	`/kyc/applications/analytics`	Thống kê KYC (pending/approved/rejected)	Admin	✅ Live
GET	`/kyc/levels`	Danh sách KYC levels	Admin	✅ Live
POST	`/kyc/levels`	Tạo KYC level mới	SuperAdmin	🔵 Cần seed
PUT	`/kyc/levels/:id`	Cập nhật KYC level	SuperAdmin	✅ Live
DEL	`/kyc/levels/:id`	Xóa KYC level	SuperAdmin	✅ Live
GET	`/kyc/service`	Danh sách verification services (3: SumSub/DeepSeek/Gemini)	Admin	✅ Live
GET	`/kyc/service/:id/check-connection`	Test kết nối KYC provider	Admin	✅ Live
POST	`/kyc/service/:id/verify`	Gửi hồ sơ lên KYC provider	Admin	✅ Live

KYC Status Flow

PENDING  →  APPROVED
         →  REJECTED
         →  RESUBMIT_REQUIRED

1.3 Support & API Keys

Method	Endpoint	Mô tả	Auth	Status
GET	`/support/tickets`	Danh sách ticket hỗ trợ	Admin	✅ Live
GET	`/support/tickets/:id`	Chi tiết ticket	Admin	✅ Live
PUT	`/support/tickets/:id`	Cập nhật / đóng ticket	Admin	✅ Live
GET	`/api-keys`	Danh sách API keys hệ thống	SuperAdmin	✅ Live
POST	`/api-keys`	Tạo API key mới	SuperAdmin	✅ Live
DEL	`/api-keys/:id`	Thu hồi API key	SuperAdmin	✅ Live

2. Finance & Trading Infrastructure

Base prefix: /api/v1/admin/

2.1 Analytics & Dashboard

Method	Endpoint	Mô tả	Auth	Status
GET	`/finance/analytics/revenue`	Doanh thu theo ngày/tháng/năm	Admin	✅ Live
GET	`/dashboard`	Dashboard tổng quan (users, volume, revenue)	Admin	✅ Live
GET	`/system/health`	Health check toàn bộ services	SuperAdmin	✅ Live

2.2 Currency Management

Method	Endpoint	Mô tả	Records	Status
GET	`/currencies/fiat`	Danh sách fiat currencies	163 currencies	✅ Live
PUT	`/currencies/fiat/:id`	Bật/tắt fiat currency	VND active	✅ Live
GET	`/currencies/crypto`	Danh sách crypto	BTC/ETH/USDT/GIV/VNL...	✅ Live
POST	`/currencies/crypto`	Thêm crypto mới	—	✅ Live
PUT	`/currencies/crypto/:id`	Cập nhật crypto	—	✅ Live
DEL	`/currencies/crypto/:id`	Xóa crypto	—	✅ Live

2.3 Payment Systems

⚠️ Phase 3 pending: Bảng internal_wallet và payment_provider_config chưa tạo. Chạy migration trước khi dùng 4 endpoints cuối.

Method	Endpoint	Mô tả	Records	Status
GET	`/payments/gateways`	Danh sách deposit gateways	15 gateways	✅ Live
POST	`/payments/gateways`	Tạo gateway mới	—	✅ Live
PUT	`/payments/gateways/:id`	Cập nhật gateway	—	✅ Live
DEL	`/payments/gateways/:id`	Xóa gateway	—	✅ Live
GET	`/payments/methods`	Danh sách withdraw methods	—	✅ Live
POST	`/payments/methods`	Tạo withdraw method	—	✅ Live
GET	`/deposits/records`	Lịch sử nạp tiền toàn hệ thống	—	✅ Live
GET	`/internal-wallet`	Tài khoản ngân hàng sàn (VietQR)	Bảng chưa tạo	🔵 Phase 3
POST	`/internal-wallet`	Thêm tài khoản ngân hàng	—	🔵 Phase 3
GET	`/payment-provider`	VietQR / VNPay / MoMo configs	Bảng chưa tạo	🔵 Phase 3
POST	`/payment-provider`	Thêm payment provider	—	🔵 Phase 3
PUT	`/payment-provider/:id`	Cập nhật credentials	—	🔵 Phase 3

Webhook Endpoints (không cần auth — signature required)

POST /api/webhook/vietqr  →  VietQR / Casso IPN → vnfAutoDepositService
POST /api/webhook/vnpay   →  VNPay IPN          → vnfAutoDepositService
POST /api/webhook/momo    →  MoMo IPN           → vnfAutoDepositService

2.4 Trading Infrastructure

Method	Endpoint	Mô tả	Records	Status
GET	`/trading/providers`	Exchange providers	3 (binance/kucoin/xt)	✅ Live
PUT	`/trading/providers/:id`	Bật/tắt provider, API key	All 3 active	✅ Live
GET	`/trading/settings`	Phí, spread, leverage (149 settings)	149 keys	✅ Live
PUT	`/trading/settings`	Cập nhật settings	—	✅ Live
GET	`/trading/markets/spot`	Spot markets	16 cặp	✅ Live
GET	`/trading/markets/binary`	Binary markets	7 cặp	✅ Live
POST	`/trading/markets/binary`	Thêm binary market	—	✅ Live
PUT	`/trading/markets/binary/:id`	Cập nhật binary market	—	✅ Live
GET	`/trading/markets/futures`	Futures markets	7 thị trường	✅ Live
GET	`/trading/binary/durations`	Binary durations	6 (1,3,5,15,30,60 phút)	✅ Live

3. Orders, Investments & Transactions

3.1 Investment Management

Method	Endpoint	Mô tả	Records	Status
GET	`/investments/plans`	Gói đầu tư	11 plans active	✅ Live
POST	`/investments/plans`	Tạo gói đầu tư mới	—	✅ Live
PUT	`/investments/plans/:id`	Cập nhật gói (profit %, result)	—	✅ Live
DEL	`/investments/plans/:id`	Xóa gói	—	✅ Live
GET	`/investments/durations`	Kỳ hạn đầu tư	7 durations	✅ Live
POST	`/investments/durations`	Thêm kỳ hạn mới	—	✅ Live
GET	`/investments/analytics`	Thống kê đầu tư	—	✅ Live

3.2 Order Management

GET /orders/binary?page=1&limit=50&status=WIN&userId=xxx&from=2026-07-01&to=2026-07-31

Method	Endpoint	Mô tả	Markets	Status
GET	`/orders/binary`	Lệnh Binary Options	7 markets, 6 durations	✅ Live
GET	`/orders/binary/:id`	Chi tiết lệnh binary	—	✅ Live
GET	`/orders/spot`	Lệnh Spot	16 exchange markets	✅ Live
GET	`/orders/spot/:id`	Chi tiết lệnh spot	—	✅ Live
GET	`/orders/futures`	Lệnh Futures	7 markets	✅ Live
GET	`/orders/ecosystem`	Lệnh nội bộ Ecosystem	5293 tokens	✅ Live

3.3 Transaction Management

Method	Endpoint	Mô tả	Auth	Status
GET	`/transactions/logs`	Toàn bộ giao dịch hệ thống	Admin	✅ Live
GET	`/transactions/transfers`	Lịch sử chuyển tiền nội bộ	Admin	✅ Live
GET	`/wallets`	Số dư tất cả ví người dùng	Admin	✅ Live
GET	`/wallets/:userId`	Ví của 1 user cụ thể	Admin	✅ Live
GET	`/withdrawals`	Danh sách yêu cầu rút tiền	Admin	✅ Live
PUT	`/withdrawals/:id/approve`	Duyệt yêu cầu rút	Admin	✅ Live
PUT	`/withdrawals/:id/reject`	Từ chối yêu cầu rút	Admin	✅ Live

4. Extensions & Add-ons

Base prefix: /api/v1/admin/extensions/ · 21/21 extensions active

4.1 Trading Platforms

Endpoint	Mô tả	Extension	Status
`/extensions/ecosystem`	Blockchain Ecosystem config	EcoSystem	✅ Active
`/extensions/futures`	Futures trading config	Futures	✅ Active
`/extensions/forex`	Forex & signals config	Forex Multi-Asset	✅ Active
`/extensions/p2p`	P2P Exchange config	P2P Exchange	✅ Active

4.2 Investment Products

Endpoint	Mô tả	Extension	Status
`/extensions/ai-investment`	AI Investment plans	AI Investments	✅ Active
`/extensions/staking`	Staking pools (0 records hiện tại)	Staking Crypto	🔵 Cần seed
`/extensions/staking/pools`	POST tạo / PUT cập nhật pool	Staking Crypto	✅ Active
`/extensions/token-sales`	ICO/IEO offerings	Token ICO	✅ Active

4.3 Marketplace Solutions

Endpoint	Mô tả	Extension	Status
`/extensions/ecommerce`	E-commerce store config	Ecommerce	✅ Active
`/extensions/ecommerce/products`	Danh sách sản phẩm	Ecommerce	✅ Active
`/extensions/nft-marketplace`	NFT Marketplace config	NFT Marketplace	✅ Active
`/extensions/nft-marketplace/listings`	Danh sách NFT	NFT Marketplace	✅ Active

4.4 Business Tools

Endpoint	Mô tả	Extension	Status
`/extensions/affiliate`	MLM/Referral config + campaigns	Multi Level Marketing	✅ Active
`/extensions/knowledge-base`	FAQ & Help center articles	Knowledge Base	✅ Active
`/extensions/email-marketing`	Email campaigns (MailWizard)	MailWizard	✅ Active
`/extensions/payment-gateway`	Payment gateway extension config	Payment Gateway	✅ Active

5. Lộ Trình Tài Liệu docx.goldvninvest.online

Đã hoàn thành

POW 4-Step Plan

/GVI-POW-4STEP-PLAN.html

Kế hoạch 4 bước PoW — Bước 1–3 đã xác minh

✅ Hoàn thành

Smart Contract System

/GVI-Network-Smart-Contract-System.html

Kiến trúc hệ thống Smart Contract

✅ Hoàn thành

Technical Proposal

/GVI-NETWORK-TECHNICAL-PROPOSAL.html

Đề xuất kỹ thuật tổng thể

✅ Hoàn thành

Phase 2 Completion Report

/gvi-network-phase-2-completion-report.html

149 settings, 21 extensions, cache fixed

✅ Hoàn thành

Phase 3 Activation Playbook

/gvi-phase-3-...html

Admin · Bank · VietQR · VNPAY · eKYC C06

✅ Hoàn thành

API Roadmap

/gvi-api-roadmap.html

50+ endpoints mapping (tài liệu này)

🔵 Mới tạo

Kế hoạch tiếp theo (TODO)

Integration Guide — VietQR/VNPAY

/gvi-integration-vietqr-vnpay.html

Casso webhook, IPN flow, test cases

🟡 TODO — Ưu tiên cao

Integration Guide — VNPT eKYC

/gvi-integration-vnpt-ekyc.html

C06 token setup, SDK embed, CORS fix

🟡 TODO — Ưu tiên cao

Admin Config Playbook

/gvi-admin-config-playbook.html

Phase 0–10 SQL seed (từ update/ADMIN_CONFIG_PLAYBOOK.md)

🟡 TODO

Smart Contract Deployment

/gvi-smart-contract-deploy.html

BSC deploy, GIV token, DEX setup

🟡 TODO

GIV Token Tokenomics

/gvi-tokenomics.html

Supply, unlock schedule, vesting

🟠 Planned

Database Schema Reference

/gvi-database-schema.html

Tất cả 160+ tables, relationships

🟠 Planned

API Security Guide

/gvi-api-security.html

Rate limit, 2FA, JWT, webhook sig

🟠 Planned

Monitoring & Alerting

/gvi-monitoring.html

PM2, Redis, MySQL health checks

🟢 Planned

6. API Standards & Conventions

Response Format chuẩn

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "meta": {
    "timestamp": "2026-07-20T10:00:00Z",
    "requestId": "req_abc123"
  }
}

Error Response

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

HTTP Status Codes

Code	Ý nghĩa	Dùng khi
`200`	OK	GET, PUT thành công
`201`	Created	POST tạo mới thành công
`204`	No Content	DELETE thành công
`400`	Bad Request	Validation error
`401`	Unauthorized	Chưa đăng nhập / JWT hết hạn
`403`	Forbidden	Không đủ permission
`404`	Not Found	Resource không tồn tại
`409`	Conflict	Duplicate (unique constraint)
`429`	Too Many Requests	Rate limit vượt 100 req/min
`500`	Internal Server Error	Lỗi backend / DB

Auth Headers

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
X-Request-ID: <uuid>

Pagination & Filtering

# Tất cả list endpoints hỗ trợ:
?page=1&limit=20&sort=createdAt&order=DESC

# Filter theo ngày
?from=2026-07-01T00:00:00Z&to=2026-07-31T23:59:59Z

# Search
?search=keyword&status=ACTIVE&roleId=55

# Max limit: 100 — Default: page=1, limit=20, order=DESC

Rate Limiting

Loại endpoint	Giới hạn	Ghi chú
API chung	100 req/min/IP	`RATE_LIMIT=100` trong .env
Auth endpoints (/login, /register)	10 req/min/IP	Chống brute force
Webhook (/api/webhook/*)	Exempt	Yêu cầu signature verification
Admin endpoints	200 req/min	Cao hơn cho internal tools

7. Checklist Triển Khai Toàn Hệ Thống

API Endpoints — Trạng thái hiện tại

Module	Endpoints	Live	Pending
User & Roles	11	11 ✅	—
KYC & Compliance	12	11 ✅	1 (kyc_level seed)
Support & API Keys	6	6 ✅	—
Finance Analytics	3	3 ✅	—
Currency Management	6	6 ✅	—
Payment Systems	13	8 ✅	5 (Phase 3 migration)
Trading Infrastructure	10	10 ✅	—
Investment Management	7	7 ✅	—
Order Management	6	6 ✅	—
Transaction Management	7	7 ✅	—
Extensions (21 active)	16	15 ✅	1 (staking data)
TỔNG CỘNG	97	90 ✅	7 pending

✅ 90/97 endpoints hoạt động. 7 endpoints còn lại phụ thuộc vào Phase 3 migration (tạo bảng internal_wallet + payment_provider_config) và seed data (kyc_level, staking_pools). Xem Phase 3 Activation Playbook để hoàn thành.