CleverInvo APIで請求書発行を自動化する方法

毎月数件以上の請求書を送っているなら、プロセスを自動化したいと思ったことがあるでしょう。プロジェクト管理ツールでプロジェクトが完了した時に自動的に請求書が生成されること、CRMで商談が成立した時に請求書が作成されること、あるいは毎月のリテイナークライアント全員の請求書をフォームを50回クリックせずにバッチ生成すること。

CleverInvo APIがこれらすべてを可能にします。このガイドでは基本をカバーします：認証、クライアントの作成、請求書の生成、請求書イベントに反応するWebhookの設定。

---

前提条件

APIはBusinessプランで利用可能です。必要なもの：

1. BusinessプランのCleverInvoアカウント
2. APIキー（ダッシュボード > APIキーから生成）
3. REST APIとJSONの基本的な知識

すべてのAPIリクエストはHTTPSを使用し、JSONレスポンスを返します。ベースURLは：

https://cleverinvo.com/api/v1

認証

AuthorizationヘッダーにAPIキーを含めます：

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients

---

クライアント管理

請求書を作成する前に、システムにクライアントが必要です。

クライアントの作成

curl -X POST https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme株式会社",
    "email": "[email protected]",
    "address": "東京都港区ビジネス通り123",
    "taxId": "T1234567890123",
    "phone": "+81-3-1234-5678"
  }'

クライアント一覧

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://cleverinvo.com/api/v1/clients?page=1&limit=20"

---

請求書の作成

APIの真の価値はここにあります。1回のAPIコールでプロフェッショナルな番号付き請求書を生成できます。

請求書の作成

curl -X POST https://cleverinvo.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cli_abc123def456",
    "currency": "JPY",
    "issueDate": "2026-03-01",
    "dueDate": "2026-03-31",
    "lineItems": [
      {
        "description": "ウェブサイトリデザイン - フェーズ1",
        "quantity": 1,
        "unitPrice": 500000
      },
      {
        "description": "フロントエンド開発",
        "quantity": 40,
        "unitPrice": 15000
      },
      {
        "description": "コンテンツ移行",
        "quantity": 8,
        "unitPrice": 10000
      }
    ],
    "notes": "お取引ありがとうございます。",
    "terms": "30日以内にお支払いください。延滞の場合は月1.5%の利息が加算されます。"
  }'

システムは自動的に：

• 次の連続請求書番号を割り当て
• 行合計、小計、総計を計算
• PDFを生成しURLを返却
• ステータスをDRAFTに設定

税込み請求書

税を含めるには、各明細項目にtaxRateを追加します：

{
  "lineItems": [
    {
      "description": "コンサルティングサービス",
      "quantity": 20,
      "unitPrice": 20000,
      "taxRate": 10
    }
  ]
}

---

請求書ステータスの管理

請求書はライフサイクルを通過します：DRAFT（下書き）、SENT（送信済み）、VIEWED（閲覧済み）、PAID（支払済み）、PARTIALLY_PAID（一部支払済み）、OVERDUE（延滞）。

ステータス更新

# 送信済みにマーク
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SENT"}'

# 支払済みにマーク
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "PAID"}'

---

一般的な連携パターン

パターン1：CRMから請求書

CRMで商談が成立した時に、自動的にクライアントを作成し（新規の場合）、請求書を生成：

async function onDealClosed(deal) {
  let client = await cleverinvo.clients.findByEmail(deal.customerEmail);
  if (!client) {
    client = await cleverinvo.clients.create({
      name: deal.customerName,
      email: deal.customerEmail,
      address: deal.customerAddress,
    });
  }

  const invoice = await cleverinvo.invoices.create({
    clientId: client.id,
    currency: deal.currency,
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems: deal.products.map((p) => ({
      description: p.name,
      quantity: p.quantity,
      unitPrice: p.price,
    })),
  });
}

パターン2：月次リテイナー請求

毎月1日にすべてのリテイナークライアントの請求書を生成：

async function generateMonthlyInvoices() {
  const clients = await cleverinvo.clients.list({ isActive: true });

  for (const client of clients.data) {
    if (client.retainerAmount) {
      await cleverinvo.invoices.create({
        clientId: client.id,
        currency: "JPY",
        issueDate: today.toISOString().split("T")[0],
        dueDate: addDays(today, 30).toISOString().split("T")[0],
        lineItems: [
          {
            description: `月額リテイナー - ${format(today, "yyyy年M月")}`,
            quantity: 1,
            unitPrice: client.retainerAmount,
          },
        ],
      });
    }
  }
}

---

レート制限

プラン	制限
Business	1分あたり100リクエスト

制限を超えると、APIは429 Too Many RequestsとRetry-Afterヘッダーを返します。

---

エラーハンドリング

すべてのエラーは一貫したJSON構造を返します：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "clientIdは必須です",
    "details": [
      {"field": "clientId", "message": "このフィールドは必須です"}
    ]
  }
}

コード	HTTPステータス	意味
UNAUTHORIZED	401	無効または欠落したAPIキー
FORBIDDEN	403	お使いのプランではAPI未対応
NOT_FOUND	404	リソースが存在しない
VALIDATION_ERROR	422	リクエストデータが無効
RATE_LIMITED	429	リクエスト過多
INTERNAL_ERROR	500	サーバーエラー（サポートへ連絡）

---

次のステップ

CleverInvo APIは既存のワークフローに適合するよう設計されています。シンプルなcronジョブでも、複雑なマルチシステム連携でも。1つのユースケースから始めて、動作確認後に拡張しましょう。

完全なAPIドキュメントは/docs/apiで利用可能です。OpenAPI仕様と追加のコード例も含まれています。

APIキーを取得する ->