API Lập Trình & AI Agents
Truy vấn, tự động hóa và đồng bộ hóa dữ liệu không gian Nine thông qua các endpoint PostgREST chuẩn, Supabase Edge Functions và các endpoint hỗ trợ AI.
Tối ưu cho AI Agents, Gemini & LLMs
Giao thức MCPllms.txt standardKết nối Nine trực tiếp với Google Gemini Connected Apps, Claude Desktop và các trợ lý AI thông qua MCP Server gốc, OpenAPI 3.0 và ngữ cảnh llms.txt.
Cài đặt Ứng dụng Kết nối Google Gemini
- 1. Mở Gemini > Tiện ích mở rộng / Ứng dụng đã kết nối > Thiết lập ứng dụng đã kết nối tùy chỉnh.
- 2. Tại ô 'Thêm liên kết ứng dụng tùy chỉnh', nhập URL Máy chủ MCP của bạn:
https://ninehoang.com/mcp?token=YOUR_API_TOKEN - 3. Để trống Client ID và Client Secret, sau đó nhấn Tiếp tục.
Các Công Cụ MCP Hỗ Trợ
| Tool Name | Description | Parameters |
|---|---|---|
| create_expense | Record an expenditure in the workspace ledger. | name (string), amount (number), category_id (enum), method_id (enum), occurred_at?, note? |
| list_expenses | Retrieve recent expense records with date filtering, category filter, search, and pagination (up to 1,000). | limit? (max 1000), offset?, category_id?, method_id?, start_date?, end_date?, search? |
| update_expense | Modify an existing expense (amount, category, vendor title, payment method, date, or notes). | id (uuid), name?, amount?, category_id?, method_id?, occurred_at?, note? |
| delete_expense | Permanently delete an expense record by its UUID. | id (uuid) |
| list_funds | List active collective funds, target budgets, and real-time balance totals. | none (returns all funds in workspace) |
| get_fund | Retrieve full details, budget targets, participants, and ledger for a specific fund. | fund_id (uuid) |
| create_fund | Create a new group fund (trips, sports seasons, event budgets). | name (string), kind? ('Travel' | 'Badminton'), currency?, target_amount?, description? |
| update_fund | Update fund name, target goal, status ('Upcoming', 'In Progress', 'Completed'), or description. | fund_id (uuid), name?, status?, target_amount?, description? |
| create_fund_transaction | Record an income contribution or expense payout in a group fund. | fund_id (uuid), name (string), amount (number), category_id (enum), method_id (enum), occurred_at? |
| list_fund_transactions | Retrieve transactions and payouts across group funds with date filtering and pagination. | fund_id?, limit? (max 1000), offset?, category_id?, start_date?, end_date? |
| delete_fund_transaction | Delete a fund transaction record by its UUID. | id (uuid) |
| list_contacts | Query member roster and contact address book in the workspace with optional search. | search? (name, nickname, or phone query) |
| create_contact | Add a new member or participant to the workspace directory. | name (string), nickname?, phone?, email?, gender?, nationality? |
| update_contact | Update member information (name, nickname, phone, email). | id (uuid), name?, nickname?, phone?, email? |
Xác thực & Đổi Token
Các ứng dụng bên ngoài xác thực qua quy trình đổi mã: đổi token không gian lấy JWT ngắn hạn có hiệu lực 1 giờ.
curl -X POST \ "https://pdkklibrvyqnatsqwtyg.supabase.co/functions/v1/api-token" \ -H "Authorization: Bearer nh_ws_YOUR_API_TOKEN" \ -H "Content-Type: application/json"
curl "https://pdkklibrvyqnatsqwtyg.supabase.co/rest/v1/personal_transactions?select=*&order=occurred_at.desc&limit=20" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "apikey: sb_publishable_gZdZ09nTdrxLCHPa36rXeg_6DraJ4Ps"
SDK & Bắt đầu nhanh
Kết nối với workspace của bạn bằng HTTP client tiêu chuẩn, JavaScript/TypeScript SDK hoặc Python.
curl "https://pdkklibrvyqnatsqwtyg.supabase.co/rest/v1/personal_transactions?select=*&order=occurred_at.desc&limit=20" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "apikey: sb_publishable_gZdZ09nTdrxLCHPa36rXeg_6DraJ4Ps"
Endpoints & Lược Đồ Dữ Liệu
Truy cập trực tiếp tài nguyên không gian qua PostgREST với cơ chế cách ly Row Level Security nghiêm ngặt.
/rest/v1/personal_transactions| Field | Type | Description / Valid Options |
|---|---|---|
| id | uuid | Primary key identifier |
| name | text | Expense description / item (max 255 chars) |
| amount | numeric | Amount in workspace currency |
| category_id | enum | Options: 'food-drinks', 'entertainment', 'local-transport', 'clothing', 'beauty-care', 'sports', 'essentials', 'fixed-expenses', 'credit-repayment', 'installment-payment', 'family-support', 'travel', 'work-expenses', 'investments', 'other'. Read from `transaction_categories` (the rows offered to Expenses), so this list can grow without a deploy. |
| method_id | enum | Slugs from the transaction_methods table: 'cash', 'bank-transfer', 'mobile-wallet', 'credit-card', 'installment'. Read the live list from /openapi.json. |
| occurred_at | timestamptz | Date and time of transaction |
| note | text | Optional context or memo |
Mã Phản Hồi HTTP & Giới Hạn Tần Suất
Các mã phản hồi chuẩn được trả về bởi PostgREST và Supabase Edge Functions.
Standard successful response for GET, PATCH, and DELETE operations.
Resource successfully created (POST personal_transactions, funds, etc.).
Malformed JSON payload, out-of-bounds numbers, or invalid enum selection.
Missing API token, expired 1-hour JWT, or token revoked via 0-ms kill switch.
Attempted to access an ungranted table (e.g. workspace_members, passwords).
Rate limit exceeded (60 req/min). Returns Retry-After header with wait seconds.
Cách Ly Dữ Liệu & Bảo Mật
Mọi yêu cầu API đều được kiểm soát bởi Postgres Row Level Security (RLS) qua public.api_workspace_id(). Các thông tin xác thực hệ thống hoàn toàn được bảo vệ.
Sẵn sàng kết nối không gian của bạn?
Tạo và quản lý các mã khóa token với quyền đọc hoặc đọc/ghi trực tiếp trong Cài đặt Không gian làm việc.