API Lập Trình & AI Agents
Vận hành không gian làm việc từ bất kỳ AI hay hệ thống nào: máy chủ MCP cho Claude, ChatGPT và Gemini, và REST API cho tích hợp — bán hàng, sản phẩm, kho, hoá đơn, nội dung và hộp thư.
Xây cho trợ lý AI — Claude, ChatGPT, Gemini
Giao thức MCPllms.txt standardDán một URL vào ứng dụng AI và đăng nhập: máy chủ MCP của Nine cung cấp 86 công cụ cho bán hàng, sản phẩm, kho, hoá đơn, nội dung và hộp thư — kèm OpenAPI 3 và llms.txt.
Thiết lập ứng dụng Gemini
- 1. Mở Gemini → Cài đặt → Ứng dụng đã kết nối → Ứng dụng tuỳ chỉnh → Thêm ứng dụng tuỳ chỉnh.
- 2. Nhập URL máy chủ MCP:
https://app.ninehoang.com/mcp - 3. Bấm Tiếp và chấp thuận kết nối trong Nine — không cần nhập client ID hay secret.
Công cụ MCP
| Tool Name | Description | Parameters |
|---|---|---|
| get_workspace | Which workspace this connection belongs to, and whether it may write. | none |
| list_sales_orders | Orders, newest first, with customer, status and totals — before tax, tax, total, cost and profit. | search?, status?, customer_id?, start_date?, end_date?, limit?, offset? |
| create_sales_order | Record a sale from products and quantities; names, prices and taxes come from the catalogue. Confirm it in the same call if you like. | lines [{ product_id, quantity, unit_price?, discount_percent? }], customer_id?, ordered_at?, note?, confirm? |
| confirm_sales_order | Confirm a draft: its cost is fixed and goods leave stock — or a delivery is created, with Inventory installed. | id |
| sales_report | Revenue before tax, cost of goods sold and gross profit for any period, with the top products and customers. | start_date?, end_date?, top? |
| list_products | The catalogue with category, cost and sales price, margin per unit, taxes and quantity on hand. | search?, category_id?, kind?, include_archived?, limit?, offset? |
| create_product | Add a product or service with its prices, taxes, tracking and opening stock. | name, kind?, category_id?, tracking?, sales_price?, cost_price?, sales_tax_ids?, purchase_tax_ids?, quantity? |
| list_replenishment | Reorder rules with on hand, incoming, outgoing, forecast — and how much to order. | product_id?, warehouse_id?, to_order_only? |
| create_invoice | A customer invoice or a vendor bill, with lines; post it to give it its number. | kind, partner_id?, reference?, invoice_date?, due_date?, lines?, post?, note? |
| record_invoice_payment | Record money received or paid against a posted invoice or bill. | invoice_id, amount, method_id, received_at?, note? |
| list_entries | A collection's entries — blog posts, services, projects — in every language, with fields, categories, tags and status. | collection, status?, limit?, offset? |
| create_entry | A new draft in any collection, in one language; its article is written next, as Markdown. | collection, title, locale?, slug?, summary?, fields?, parent_id? |
| set_article | Write one language of an entry's article as Markdown — headings, lists, callouts, galleries, embeds. | kind, id, locale, markdown |
| publish_article | Publish a draft now or at a set time, or take it off the site — when the workspace lets assistants publish. | kind, id, action?, at? |
| list_messages | Leads from the website's contact form, newest first, with where each stands in triage. | status?, search?, limit?, offset? |
| create_many | Up to 50 records of any types in one call — one approval. A later item can use an earlier one's result: "$0.id". | items [{ tool, arguments }] |
Xác thực
Ứng dụng AI kết nối bằng OAuth 2.1: đăng nhập, chọn không gian làm việc và mức quyền. Hệ thống tích hợp gửi token của không gian làm việc trong mỗi yêu cầu — Authorization: Bearer nh_ws_…. Token không tự hết hạn, và thu hồi là ngắt truy cập ngay.
curl "https://app.ninehoang.com/api/v1/sales_orders?select=*&order=ordered_at.desc&limit=20" \ -H "Authorization: Bearer nh_ws_YOUR_API_TOKEN"
curl -X POST "https://app.ninehoang.com/api/v1/tools/confirm_sales_order" \
-H "Authorization: Bearer nh_ws_YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "ORDER_UUID"}'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.
# 1. Read rows — any table, with PostgREST filters
curl "https://app.ninehoang.com/api/v1/sales_orders?select=*&order=ordered_at.desc&limit=20" \
-H "Authorization: Bearer nh_ws_YOUR_API_TOKEN"
# 2. Run an action — the same rules the MCP server applies
curl -X POST "https://app.ninehoang.com/api/v1/tools/confirm_sales_order" \
-H "Authorization: Bearer nh_ws_YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id": "ORDER_UUID"}'Endpoints & Lược Đồ Dữ Liệu
Mọi bảng qua ngôn ngữ truy vấn của PostgREST, và mọi nghiệp vụ qua /api/v1/tools — đều giới hạn trong không gian làm việc của token bằng row-level security.
/api/v1/expenses_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ã trạng thái HTTP
Lỗi từ chính API là { error } bằng lời; từ một bảng là { code, message } của PostgREST.
Rows read, updated or deleted, or an action's result.
Rows created through POST /api/v1/{resource}; the created rows come back.
An action refused its arguments — { error } says why, in words — or a malformed filter or payload.
Missing, revoked or expired token, or the workspace's API switched off. AI apps reconnect through OAuth.
A read-only token tried to write, or the app that owns the data is not installed.
No such resource or action; GET /api/v1 and GET /api/v1/tools list them.
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.