开发者门户

编程式 API 与 AI 智能体

从任何 AI 或系统运营你的工作区：面向 Claude、ChatGPT 和 Gemini 的 MCP 服务器，以及用于集成的 REST API——销售、产品、库存、开票、内容和收件箱。

为 AI 助手打造——Claude、ChatGPT、Gemini

MCP 协议llms.txt standard

在 AI 应用中粘贴一个 URL 并登录：Nine 的 MCP 服务器提供覆盖销售、产品、库存、开票、内容和收件箱的 86 个工具，同时提供 OpenAPI 3 和 llms.txt。

Gemini 应用设置

1. 打开 Gemini → 设置 → 已连接的应用 → 自定义应用 → 添加自定义应用。
2. 输入 MCP 服务器 URL：
https://app.ninehoang.com/mcp
3. 点击下一步，并在 Nine 中批准连接——无需输入客户端 ID 或密钥。

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 }]

认证

AI 应用通过 OAuth 2.1 连接：登录、选择工作区和权限级别。集成系统在每个请求中发送工作区令牌——Authorization: Bearer nh_ws_…。令牌不会自行过期，撤销后访问立即结束。

1. 读取行——任意表，支持筛选、排序和分页

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. 运行操作——与 MCP 服务器相同的规则

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 与快速入门

使用标准 HTTP 客户端、JavaScript/TypeScript SDK 或 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"}'

资源端点与数据结构

所有表都可通过 PostgREST 查询语言访问，所有业务步骤都可通过 /api/v1/tools 完成——两者都由行级安全限定在令牌所属的工作区。

GETPOSTPATCHDELETE

/api/v1/expenses_transactions

Workspace expense ledger, spending records, and day-to-day outlays.

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

HTTP 状态码

API 本身的错误为 { error }（用文字说明原因）；表端点的错误为 PostgREST 的 { code, message }。

200 OK

Rows read, updated or deleted, or an action's result.

201 Created

Rows created through POST /api/v1/{resource}; the created rows come back.

400 Bad Request

An action refused its arguments — { error } says why, in words — or a malformed filter or payload.

401 Unauthorized

Missing, revoked or expired token, or the workspace's API switched off. AI apps reconnect through OAuth.

403 Forbidden

A read-only token tried to write, or the app that owns the data is not installed.

404 Not Found

No such resource or action; GET /api/v1 and GET /api/v1/tools list them.

租户隔离与数据安全

每个 API 请求均由 Postgres Row Level Security (RLS) 自动隔离。系统凭据及内部身份验证配置被完全禁止外部访问。

Zero Cross-Tenant LeakPostgres RLS filters every table query automatically by workspace ID.

Excluded TablesWorkspace members, passwords, billing, and credentials are completely ungranted.

Instant kill switchTurning off the workspace API switch, or revoking one token, ends access on the next request — AI apps get a 401 and offer to reconnect.

准备好接入您的工作区了吗？

直接在工作区设置中生成并管理具备只读或读写权限的 API 令牌。

前往工作区 API 设置