API・AIエージェントアクセス

SimplyQuoteはREST APIを公開しており、AIエージェントやスクリプト、連携ツールがあなたの代理として見積書・請求書を扱えます。アクセスはスコープ付きで取り消し可能な個人アクセストークンで管理されます。

1. APIアクセスを有効にする

1. 設定ページを開いてログインします
2. 「API・AIエージェントアクセス」セクションまでスクロールします。
3. トークンに名前を付け、スコープを選択して「トークンを作成」をクリックします。
4. トークンをすぐにコピーしてください。セキュリティのため、一度しか表示されません。

2. リクエストを送る

AuthorizationヘッダーでトークンをBearerトークンとして送信します:

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. ドキュメントの作成と更新

見積書・請求書の作成・更新は、書き込みスコープを持つ同じトークンで行います。合計額は常にサーバー側で計算されます:

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

成功レスポンス(一覧も同様で、quotes/invoicesにtotal/page/limit/has_moreが付きます):

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

一覧取得とページネーション

一覧エンドポイントはupdated_since(ISO 8601)、page(既定1)、limit(既定20、最大100)、status(大文字小文字不問、不明値は無視)を受け付けます。レスポンスにはtotal、page、limit、has_moreが含まれます。

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

作成・更新時のフィールド規則

POSTではitemsが必須です。空でない配列で、各行に空でないdescription、quantity > 0(既定1)、unit_price >= 0(既定0)が必要です。tax_rateはパーセント(0–100)で、作成時にtax_rate > 0ならtax_enabled扱いです。currencyは大文字で保存されます。issue_dateは解釈可能な日付なら何でも可(YYYY-MM-DDで保存)。見積書はexpiry_date、請求書はdue_dateを使います(どちらの別名も可、nullでクリア)。ステータスは見積書がdraft|sent、請求書がdraft|sent|viewed|paid|cancelledで、paidにするとpaid_atが記録されます。合計額は常にサーバー側で再計算されます。

4. AIエージェントから使う

エージェントにベースURL、トークン、下記のエンドポイント一覧を伝えます。ツール呼び出し対応エージェント(Claude、GPT、LangChainなど)向けの指示例:

私のSimplyQuoteアカウントにアクセスできます。
ベースURL: https://simplyquote.net
すべてのリクエストでヘッダーを送信: Authorization: Bearer sq_あなたのトークン
利用可能なエンドポイント: GET/POST /api/v1/quotes、GET/PATCH /api/v1/quotes/{id}、
GET/POST /api/v1/invoices、GET/PATCH /api/v1/invoices/{id}、POST /api/mcp
一覧は?page、?limit(最大100)、?status、?updated_sinceに対応し、{ success:true, data:{ quotes|invoices, total, page, limit, has_more } }を返します。
単票取得は素のオブジェクトを返します。{id}はUUIDであり、伝票番号ではありません。
ドキュメントの作成にはPOSTを使用し、itemsにはdescription・quantity・unit_priceを必ず含めてください。

5. MCPで接続(エージェントに推奨)

SimplyQuoteには/api/mcpに組み込みのMCP(Model Context Protocol)サーバーがあります(ステートレスなstreamable HTTP、JSON-RPC 2.0)。リモートMCPサーバーに対応するエージェント(Claude、ChatGPT、Cursor、VS Codeなど)はトークンだけで直接接続でき、プロンプトの工夫は不要です。利用可能なツール:

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

ツール呼び出し例(JSON-RPC 2.0 — バッチは拒否、通知は202、GETは405を返します):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

各ツール呼び出しにはトークンのスコープが適用されます。読み取り専用トークンでは一覧・取得のみ可能で、見積書や請求書の作成には対応する書き込みスコープが必要です。

エンドポイント

スコープ

• quotes:read — 見積書の読み取り
• invoices:read — 請求書の読み取り
• clients:read — 予約済み — 顧客専用エンドポイントはまだありません(顧客情報は見積書・請求書に含まれます)
• quotes:write — 見積書の作成・更新
• invoices:write — 請求書の作成・更新
• clients:write — 予約済み — 顧客専用エンドポイントはまだありません(顧客情報は見積書・請求書の保存時に暗黙的に作成・更新されます)

レスポンス形式とエラー

RESTエンドポイントには2つの形式があります。どちらが適用されるか確認してください:

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

単票取得は上記の素のオブジェクトを返します(ラッパーなし)。エラーはフラットな{ error, message }形式です(id不明時は404など)。一覧およびPOST/PATCHは常にラッパー形式です。

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — 成功時はtrue、失敗時はfalse
• data — 成功時のペイロード
• error — 失敗時のエラーコード・メッセージ・詳細(任意)

主なエラーコード:

• UNAUTHORIZED — トークンがない・無効・期限切れ(HTTP 401)
• FORBIDDEN — トークンに必要なスコープがない(HTTP 403)
• VALIDATION_ERROR — リクエストボディの検証に失敗(HTTP 400)
• NOT_FOUND — 対象のドキュメントが存在しない(HTTP 404)
• DATABASE_ERROR — 処理中のストレージエラー(HTTP 500)
• RATE_LIMIT — リクエストが多すぎます。後でお試しください(HTTP 429)

Webhook・OAuth・完全リファレンス

Webhook: GET/POST/PATCH/DELETE /api/v1/webhooksで購読を管理します(有効なトークンなら可、専用スコープ不要)。urlは公開HTTPSエンドポイントである必要があります。シークレットは作成時のみ返されます。配信はX-SimplyQuote-Signature(HMAC-SHA256)ヘッダーで検証してください。

パートナーアプリは個人トークンの代わりにOAuth 2.0(/api/oauth/authorize、/api/oauth/token、/api/oauth/revoke)を使います。詳細はdocs/API.mdと/api/v1/openapi.jsonの機械可読仕様を参照してください。

セキュリティに関する注意

• トークンはハッシュ化して保存され、SimplyQuoteが生のトークンを保持することはありません。
• エージェントに必要なスコープだけを付与してください。通常は読み取り専用で十分です。
• 設定からいつでもトークンを取り消でき、直ちにアクセスが遮断されます。
• エージェント用の機械可読な仕様は次のURLで公開しています: /api/v1/openapi.json