> APIドキュメント

JSONBill 完全APIリファレンス - JSONデータからPDF請求書と精算書を作成

概要

JSONBillは超軽量のJSONベース請求システムです。JSONデータからPDF請求書と精算書を作成するためのRESTful APIを提供します。

関連ドキュメント： x402 支払い

認証

すべてのAPIエンドポイントには Authorization ヘッダーによる認証が必要です：

Authorization: Bearer <token>

<token> にはJWTトークンまたはAPI keyを使用できます。システムが自動的にトークンの種類を検出します。

ポイント

PDF生成ごとに1 Quailyポイントを消費します。API key認証を使用する場合、タスク作成前にポイント残高がチェックされます。アカウントに十分なポイントがあることをご確認ください。

x402 支払い（v2）

JSONBill は x402 v2 によるオンチェーンの従量払いに対応しています。対応ネットワーク/資産：Base（eip155:8453）USDC。

x402 で支払う場合、Authorization ヘッダーは不要です。詳細は x402 支払いガイドを参照してください。

流れ：

PAYMENT-SIGNATURE を付けずに POST /tasks/docs を呼び出す。
402 Payment Required が返り、レスポンスヘッダーに PAYMENT-REQUIRED（base64 の PaymentRequired JSON）。
x402 クライアントで署名し、PAYMENT-SIGNATURE を付けて再送する。

再送例（ヘッダーのみ）：

Content-Type: application/json
PAYMENT-SIGNATURE: <base64 payment payload>

APIエンドポイント

文書タスクの作成

エンドポイント: POST /tasks/docs

説明: JSONデータから新しいPDF請求書/精算書生成タスクを作成します。

リクエストヘッダー:

Content-Type: application/json
Authorization: Bearer <token>

リクエストボディ例:

{
  "type": "invoice",
  "lang": "ja",
  "theme": "classic",
  "params": {
    "id": "20260102-INC-1",
    "date": "2026-01-02T09:30:01.001Z",
    "currency": "JPY",
    "company_name": "サンプル株式会社",
    "company_address": "東京都渋谷区神南1-2-3",
    "company_email": "info@example.co.jp",
    "tax_number": "T1234567890123",
    "bill_to_company": "クライアント株式会社",
    "bill_to_address": "東京都港区六本木4-5-6",
    "doc": {
      "title": "Invoice",
      "description": "2025年12月のコンサルティングサービス"
    },
    "summary": {
      "period_start": "2025-12-01T00:00:00.000Z",
      "period_end": "2026-01-01T00:00:00.000Z",
      "title": "コンサルティングサービス",
      "currency": "JPY",
      "total_include_tax": 1100000,
      "tax_rate": 0.10,
      "total_include_tax_quote_amount": 7333,
      "total_include_tax_quote_symbol": "USD"
    },
    "detail_items": [
      {
        "date": "2025-12-15T00:00:00.000Z",
        "title": "プロジェクトAlpha - フェーズ1",
        "desc": "初期開発とセットアップ",
        "currency": "JPY",
        "total_include_tax": 550000,
        "total_include_tax_quote_amount": 3666.5,
        "total_include_tax_quote_symbol": "USD"
      },
      {
        "date": "2025-12-28T00:00:00.000Z",
        "title": "プロジェクトAlpha - フェーズ2",
        "desc": "テストとデプロイメント",
        "url": "https://example.com/project-alpha",
        "total_include_tax": 550000
      }
    ],
    "payment": {
      "instruction": {
        "receive_account_bank": "みずほ銀行",
        "receive_account_branch": "渋谷支店",
        "receive_account_number": "1234567",
        "receive_deposit_type": "普通",
        "receive_account_name": "サンプル株式会社"
      }
    }
  }
}

リクエストパラメータ:

パラメータ	型	必須	説明
`type`	string	いいえ	文書タイプ：`invoice` または `settlementstatement`。デフォルト：`invoice`
`lang`	string	いいえ	言語コード（`en`、`ja`、`zh_cn`、`zh_tw`）。デフォルト：`en`
`theme`	string	いいえ	文書テーマ。デフォルト：`classic`
`params`	object	はい	文書データ（文書データ形式を参照）

精算書の注意点：

bill_to_company / bill_to_address の代わりに recipient_company / recipient_address を使用してください。
payment.instruction は無視され、payment.result のみ表示されます。

利用可能なテーマ:

テーマ	説明
`classic`	伝統的な請求書レイアウト、ベースライン出力と同じ
`modern`	ダッシュボードスタイル、請求先とサマリーを2列レイアウトで表示
`compact`	modernの高密度版、余白を削減、1ページに収まりやすい
`spotlight`	合計金額/支払金額を先頭に大きく表示、素早く確認可能
`ledger`	会計スタイル、明細を先に、合計とサマリーを最後に表示
`split`	明細を先に、フッターで支払いとサマリーを2列表示

各テーマのPDF出力はこちら：テーマサンプル。

レスポンス:

{
  "data": {
    "id": 1,
    "trace_id": "f4730554-791c-463b-9a27-aeacdfb02cf2",
    "status": 0,
    "created_at": "2026-01-02T09:30:01.001Z",
    "updated_at": "2026-01-02T09:30:01.001Z"
  },
  "ts": 1767766187
}

タスクステータスコード:

0: 初期化（タスク作成済み）
1: スケジュール済み
2: 実行中
3: 完了
4: エラー

タスクステータスの確認

エンドポイント: GET /tasks/{traceID}

説明: 文書生成タスクのステータスを確認します。

レスポンス:

{
  "data": {
    "id": 1,
    "trace_id": "f4730554-791c-463b-9a27-aeacdfb02cf2",
    "status": 3,
    "created_at": "2026-01-02T09:30:01.001Z",
    "updated_at": "2026-01-02T09:30:05.001Z"
  },
  "ts": 1767766191
}

PDFのダウンロード

エンドポイント: GET /tasks/{traceID}.pdf

説明: 生成されたPDF文書をダウンロードします。タスクステータスが3（完了）の場合のみ利用可能です。

レスポンス: PDFファイル

注意: PDFファイルは1時間後にサーバーから削除されます。

ポイント残高の確認

エンドポイント: GET /proxy/credits/balance

説明: 現在のポイント残高を確認します。

レスポンス:

{
  "data": {
    "user_id": 123,
    "balance_credit": "10.00",
    "status": 1
  },
  "ts": 1767766187
}

文書データ形式

基本文書フィールド

フィールド	型	必須	説明
`id`	string	いいえ	文書ID/番号
`date`	string	いいえ	文書日付（ISO 8601形式）
`currency`	string	いいえ	通貨コード（例：`USD`、`EUR`、`JPY`、`CNY`）。任意の通貨コードに対応。
`company_name`	string	はい	御社の会社名
`company_address`	string	いいえ	御社の住所
`company_email`	string	いいえ	御社のメールアドレス
`tax_number`	string	いいえ	税務登録番号
`bill_to_company`	string	いいえ	請求先会社名（請求書のみ）
`bill_to_address`	string	いいえ	請求先住所（請求書のみ）
`recipient_company`	string	いいえ	受取先会社名（精算書）
`recipient_address`	string	いいえ	受取先住所（精算書）
`doc`	object	いいえ	ドキュメント情報（ドキュメントフィールド参照）

ドキュメントフィールド

doc オブジェクトで文書に表示するドキュメントのタイトルと説明を設定します：

フィールド	型	必須	説明
`title`	string	いいえ	ドキュメントタイトル
`description`	string	いいえ	ドキュメント説明

サマリーフィールド

summary オブジェクトには文書の合計と期間情報が含まれます：

フィールド	型	必須	説明
`title`	string	いいえ	サマリータイトル/説明
`period_start`	string	いいえ	請求期間開始日（ISO 8601）
`period_end`	string	いいえ	請求期間終了日（ISO 8601）
`currency`	string	いいえ	このサマリーの通貨コード（未指定時はトップレベルの `currency`）
`total_exclude_tax`	number	いいえ	税抜合計金額
`total_include_tax`	number	いいえ	税込合計金額
`tax`	number	いいえ	税額
`tax_rate`	number	いいえ	税率（例：`0.10` で 10%）
`total_include_tax_quote_amount`	number	いいえ	参考通貨での相当金額
`total_include_tax_quote_symbol`	string	いいえ	参考通貨記号（例：`USD`）

補足：

total_exclude_tax と total_include_tax は二者択一です。
total_exclude_tax を使う場合は tax または tax_rate を指定できます。

参考通貨の例：

JPYで請求するが、クライアントが他の通貨での金額を確認したい場合：

"summary": {
  "total_include_tax": 1100000,
  "total_include_tax_quote_amount": 7333,
  "total_include_tax_quote_symbol": "USD"
}

これにより文書に暗黙の為替レート 1 USD = 150 JPY が表示されます。

税抜き例：

"summary": {
  "total_exclude_tax": 1000000,
  "tax": 100000
}

明細項目

detail_items 配列には文書の各行項目が含まれます：

フィールド	型	必須	説明
`date`	string	いいえ	項目日付（ISO 8601）
`title`	string	いいえ	項目タイトル
`desc`	string	いいえ	項目説明
`url`	string	いいえ	関連URL
`currency`	string	いいえ	この項目の通貨コード（未指定時はトップレベルの `currency`）
`total_exclude_tax`	number	いいえ	項目の税抜金額
`total_include_tax`	number	いいえ	項目の税込金額
`total_include_tax_quote_amount`	number	いいえ	参考通貨での相当金額（項目レベル）
`total_include_tax_quote_symbol`	string	いいえ	参考通貨記号（項目レベル）
`tax`	number	いいえ	項目の税額

補足：

total_exclude_tax と total_include_tax は二者択一です。
total_exclude_tax を使う場合は tax を指定できます。

例：

"detail_items": [
  {
    "date": "2025-12-15T00:00:00.000Z",
    "title": "コンサルティング - 第1週",
    "desc": "戦略立案と分析",
    "total_exclude_tax": 250000,
    "tax": 20000
  },
  {
    "date": "2025-12-22T00:00:00.000Z",
    "title": "コンサルティング - 第2週",
    "desc": "実装サポート",
    "url": "https://example.com/report",
    "total_exclude_tax": 250000,
    "tax": 20000
  }
]

支払い方法

payment オブジェクトには2つの任意セクションがあります：

instruction：支払い指示（どのように支払うか）。
result：支払い結果（任意）。

どちらも disabled を指定すると、文書上で非表示にできます。

精算書の注意点： payment.result のみ表示され、payment.instruction は無視されます。

銀行振込（指示）

"payment": {
  "instruction": {
    "receive_account_bank": "みずほ銀行",
    "receive_account_branch": "渋谷支店",
    "receive_account_number": "1234567",
    "receive_deposit_type": "普通",
    "receive_account_name": "サンプル株式会社"
  }
}

SWIFT送金（指示）

"payment": {
  "instruction": {
    "receive_account_swift": "MHBKJPJT",
    "receive_account_number": "1234567",
    "receive_account_name": "Sample Corporation",
    "receive_account_bank": "Mizuho Bank",
    "receive_account_branch": "Shibuya, Tokyo"
  }
}

暗号通貨（指示）

"payment": {
  "instruction": {
    "receive_crypto_network": "ETH Mainnet",
    "receive_crypto_address": "0x1234567890abcdef1234567890abcdef12345678",
    "receive_crypto_currency": "USDC",
    "receive_crypto_memo": ""
  }
}

フィールド	説明
`instruction.receive_crypto_network`	ブロックチェーンネットワーク（例：ETH Mainnet、Polygon、Solana）
`instruction.receive_crypto_address`	支払いを受け取るウォレットアドレス
`instruction.receive_crypto_currency`	暗号通貨シンボル（例：USDC、USDT、ETH）
`instruction.receive_crypto_memo`	任意のメモまたは宛先タグ（XRP、XLMなどのネットワーク用）

支払い結果（任意）

"payment": {
  "result": {
    "payment_method": "Bank transfer",
    "amount_paid": 5200,
    "currency": "USD",
    "paid_date": "2026-01-27",
    "tx_id": "TXN-12345"
  }
}

フィールド	説明
`result.payment_method`	実際の支払い方法（自由記述）
`result.amount_paid`	実際の支払い金額
`result.currency`	支払い金額の通貨
`result.paid_date`	支払い日（ISO文字列）
`result.tx_id`	取引または参照ID

目次

概要

認証

ポイント

x402 支払い（v2）

APIエンドポイント

文書タスクの作成

タスクステータスの確認

PDFのダウンロード

ポイント残高の確認

文書データ形式

基本文書フィールド

ドキュメントフィールド

サマリーフィールド

明細項目

支払い方法

銀行振込（指示）

SWIFT送金（指示）

暗号通貨（指示）

支払い結果（任意）