開発者ポータル

プログラム用 API & AI エージェント

どの AI やシステムからでもワークスペースを運用できます。Claude・ChatGPT・Gemini 向けの MCP サーバーと、連携用の REST API — 販売、商品、在庫、請求、コンテンツ、受信箱。

AI アシスタントのために — Claude、ChatGPT、Gemini

MCP プロトコルllms.txt standard

AI アプリに URL を 1 つ貼り付けてサインインするだけ。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 設定へ