APIリファレンス

ビジネスプラン

CleverInvoをワークフローに統合しましょう。クライアントの管理、請求書の作成、PDFのダウンロードをプログラムで実行できます。

認証

すべてのAPIリクエストにはBearerトークンが必要です。ダッシュボードからAPIキーを作成し、Authorizationヘッダーに含めてください。

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

クライアント

GET/api/v1/clients

すべてのアクティブなクライアントを一覧表示します。ページネーションと検索をサポートしています。

レスポンス
{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Main St, New York, NY 10001",
      "taxId": "US-123456789",
      "phone": "+1-555-0100",
      "notes": "Net 30 terms",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/clients

新しいクライアントを作成します。プランのクライアント制限が適用されます。

リクエストボディ
{
  "name": "Acme Corp",
  "email": "[email protected]",
  "address": "123 Main St, New York, NY 10001",
  "taxId": "US-123456789",
  "phone": "+1-555-0100",
  "notes": "Net 30 terms"
}
レスポンス
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
GET/api/v1/clients/:id

IDで単一のクライアントを取得します。

レスポンス
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
PUT/api/v1/clients/:id

クライアントを更新します。すべてのフィールドが変更可能です。

リクエストボディ
{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}
レスポンス
{
  "data": {
    "id": "clx...",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0200",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}
DELETE/api/v1/clients/:id

クライアントをソフトデリートします。isActiveをfalseに設定します。既存の請求書があるクライアントはハードデリートできません。

レスポンス
204 No Content

請求書

GET/api/v1/invoices

請求書を一覧表示します。ページネーション、検索、clientIdまたはステータスによるフィルタリングをサポートしています。

レスポンス
{
  "data": [
    {
      "id": "clx...",
      "clientId": "clx...",
      "invoiceNumber": "INV-0001",
      "currency": "USD",
      "issueDate": "2024-06-01",
      "dueDate": "2024-07-01",
      "subtotal": 5000.00,
      "taxTotal": 500.00,
      "discountTotal": 0,
      "total": 5500.00,
      "status": "SENT",
      "createdAt": "2024-06-01T00:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/invoices

請求書を作成し、PDFを自動生成します。プラン制限が適用されます。

リクエストボディ
{
  "clientId": "clx...",
  "invoiceNumber": "INV-0042",
  "currency": "USD",
  "issueDate": "2024-06-01",
  "dueDate": "2024-07-01",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Thank you for your business",
  "terms": "Payment due within 30 days"
}
レスポンス
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}
GET/api/v1/invoices/:id

明細項目やクライアント情報を含む請求書の完全な詳細を取得します。

レスポンス
{
  "data": {
    "id": "clx...",
    "clientId": "clx...",
    "invoiceNumber": "INV-0042",
    "currency": "USD",
    "issueDate": "2024-06-01",
    "dueDate": "2024-07-01",
    "lineItems": [
      {
        "description": "Web Development",
        "quantity": 40,
        "unitPrice": 125.00,
        "amount": 5000.00,
        "taxRate": 10
      }
    ],
    "subtotal": 5000.00,
    "taxTotal": 500.00,
    "discountTotal": 0,
    "total": 5500.00,
    "status": "SENT",
    "notes": "Thank you for your business",
    "terms": "Payment due within 30 days",
    "sentViaEmail": true,
    "sentAt": "2024-06-01T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "client": {
      "name": "Acme Corp",
      "email": "[email protected]"
    }
  }
}
PUT/api/v1/invoices/:id

請求書を更新します。下書きの請求書のみ変更可能です。

リクエストボディ
{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}
レスポンス
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}
DELETE/api/v1/invoices/:id

請求書と生成されたPDFを完全に削除します。

レスポンス
204 No Content
GET/api/v1/invoices/:id/pdf

請求書をPDFファイルとしてダウンロードします。Content-Dispositionヘッダー付きのバイナリPDFを返します。

レスポンス
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-0042.pdf"

<binary PDF data>

ページネーション

一覧エンドポイントは以下のクエリパラメータを受け付けます：

パラメータデフォルト説明
page1ページ番号（最小：1）
limit201ページあたりの項目数（1〜100）
search—名前、メール、または請求書番号でフィルタリング（最大255文字）
clientId—クライアントで請求書をフィルタリング（請求書のみ）
status—ステータスでフィルタリング：DRAFT、SENT、VIEWED、PAID、PARTIALLY_PAID、OVERDUE
GET /api/v1/clients?page=2&limit=10&search=acme

エラー

APIは標準のHTTPステータスコードを返します。エラーレスポンスにはerrorフィールドを含むJSONボディが含まれます。

ステータス説明
400Bad Request — 無効なパラメータまたは必須フィールドの欠落
401Unauthorized — 無効または欠落したAPIキー
403Forbidden — プラン制限に達しました（クライアント、請求書、または機能）
404Not Found — リソースが存在しないかアクセスできません
429Too Many Requests — レート制限を超過しました
500Internal Server Error — 予期しないエラー、後でもう一度お試しください
{
  "error": "Missing required field: name"
}

レート制限

APIリクエストはAPIキーごとに毎分120リクエストに制限されています。

制限を超過すると、リクエストは429 Too Many Requestsを返します。再試行する前にお待ちください。