APIリファレンス

FUNBREW PDF APIの全エンドポイントのリファレンスです。

SDK

公式クライアントライブラリを提供しています。GitHubリポジトリから利用できます。

言語	GitHub	インストール
PHP	`FUNBREW/pdf-php`	`composer require funbrew/pdf-php`
Node.js	`FUNBREW/pdf-node`	`npm install @funbrew/pdf`
Python	`FUNBREW/pdf-python`	`pip install funbrew-pdf`

PHP

$pdf = new Funbrew\Pdf\FunbrewPdf('sk-your-api-key');
$result = $pdf->fromHtml('<h1>Hello</h1>');
echo $result['data']['download_url'];

Node.js

const { FunbrewPdf } = require('@funbrew/pdf');
const pdf = new FunbrewPdf('sk-your-api-key');
const result = await pdf.fromHtml('<h1>Hello</h1>');
console.log(result.data.download_url);

Python

from funbrew_pdf import FunbrewPdf
pdf = FunbrewPdf("sk-your-api-key")
result = pdf.from_html("<h1>Hello</h1>")
print(result["data"]["download_url"])

認証

すべてのAPIリクエストにはAPIキーが必要です。リクエストヘッダーに Bearer Token として含めてください。

Authorization: Bearer sk-your-api-key

X-API-Key X-API-Key ヘッダーやクエリパラメータ ?api_key=... でも認証できます。

APIキーはダッシュボードから発行できます。発行時に一度だけ表示されるので、安全に保管してください。

PDFエンジン選択

FUNBREW PDFは2つのレンダリングエンジンを提供します。デフォルトはChromiumベースの高品質エンジンです。

値	レンダラー	速度	CSS対応
`"quality"`	Gotenberg (Chromium)	通常（1-3秒）	CSS3 / Flexbox / Grid
`"fast"`	wkhtmltopdf	高速（0.5-2秒）	CSS2.1 + 一部CSS3

// Chromiumエンジンで生成（デフォルト）
{
  "html": "<div style='display:flex'>...</div>",
  "options": { "engine": "quality" }
}

engine未指定時はquality（Chromium）が使われます。高速性が必要な大量生成にはengine=fastを指定してください。

レート制限

APIリクエストにはプランに応じた分間リクエスト上限があります。

プラン	上限
Free	10 回/分
Starter	30 回/分
Basic	60 回/分
Standard	120 回/分
Enterprise	無制限

レスポンスヘッダー

すべてのAPIレスポンスに以下のヘッダーが含まれます。

ヘッダー	説明
`X-RateLimit-Limit`	分間リクエスト上限
`X-RateLimit-Remaining`	残りリクエスト数
`X-RateLimit-Reset`	制限リセット時刻（UNIXタイムスタンプ）

制限超過時

上限を超えると 429 Too Many Requests が返されます。Retry-After ヘッダーの秒数を待ってからリトライしてください。

{
  "success": false,
  "message": "Rate limit exceeded. Please retry later.",
  "retry_after": 42
}

HTML → PDF

POST/api/pdf/generate-from-html

HTMLコンテンツからPDFを生成します。

パラメータ

名前	型	必須	説明
`html`	string	o	HTMLコンテンツ（最大5MB）
`options.page-size`	string		A3, A4, A5, Letter, Legal
`options.engine`	string		PDFエンジン。"quality"（Chromium, デフォルト）または "fast"（wkhtmltopdf）
`options.margin-*`	number		top/right/bottom/left（mm, 0-50）
`filename`	string		ダウンロード時の表示ファイル名
`expiration_hours`	integer		有効期限（1-168, デフォルト24）
`max_downloads`	integer		最大DL数（0-100, 0=無制限, デフォルト10）
`watermark`	string		透かしテキスト
`email.to`	string		PDF添付メールの送信先
`email.subject`	string		メール件名
`email.body`	string		メール本文

リクエスト例

curl -X POST https://your-domain/api/pdf/generate-from-html \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>", "options": {"page-size": "A4"}}'

レスポンス

{
  "success": true,
  "data": {
    "filename": "uuid.pdf",
    "original_name": "請求書_2026年3月.pdf",
    "download_url": "https://.../api/pdf/download/uuid.pdf",
    "file_size": 45321,
    "expires_at": "2026-03-21T12:00:00.000000Z",
    "max_downloads": 10,
    "remaining_downloads": 10
  }
}

URL → PDF

POST/api/pdf/generate-from-url

URLで指定したWebページをPDFに変換します。

名前	型	必須	説明
`url`	string	o	変換対象のURL（JS実行・HTTPS対応）
`filename`	string		ダウンロード時の表示ファイル名
`options.*`			HTML → PDFと同じ
`email.*`			HTML → PDFと同じ

テンプレート → PDF

POST/api/pdf/generate-from-template

事前登録したテンプレートに変数を埋め込んでPDFを生成します。

名前	型	必須	説明
`template`	string	o	テンプレートのslug
`variables`	object		テンプレート変数 `{"name": "Taro"}`
`filename`	string		ダウンロード時の表示ファイル名
`options.*`			HTML → PDFと同じ

バッチ生成

POST/api/pdf/batch

複数のPDFを一括で非同期生成します。

名前	型	必須	説明
`items`	array	o	生成リクエストの配列（最大100件）
`items[].type`	string	o	html or url
`items[].html`	string	*	type=htmlの場合必須
`items[].url`	string	*	type=urlの場合必須

GET/api/pdf/batch/{batch_id}

バッチの進捗状況を確認します。

PDFマージ

POST/api/pdf/merge

既存の複数PDFを1つに結合します。

名前	型	必須	説明
`filenames`	array	o	結合するPDFのファイル名配列（2-50件）

ダウンロード

GET/api/pdf/download/{filename}

生成済みPDFをダウンロードします。DLカウントが増加します。

ファイル情報

GET/api/pdf/info/{filename}

PDFファイルのメタデータ（サイズ、残りDL数、有効期限等）を取得します。

ファイル削除

DELETE/api/pdf/delete/{filename}

PDFファイルを削除します。

テンプレートCRUD

GET/api/templates

テンプレート一覧を取得します。

POST/api/templates

テンプレートを作成します。html_content 内で変数プレースホルダーが使えます。

名前	型	必須	説明
`name`	string	o	テンプレート名
`slug`	string	o	一意の識別子（小文字英数字+ハイフン）
`html_content`	string	o	HTMLテンプレート
`variables`	array		変数定義 `[{"name": "x", "required": true}]`

PUT/api/templates/{id}

DELETE/api/templates/{id}

メール送信

PDF生成時に、生成されたPDFを添付してメールを送信できます。2つの方法があります。

A) APIリクエストで指定

生成リクエストに email パラメータを追加すると、生成完了後にPDFを添付してメール送信します。

curl -X POST https://your-domain/api/pdf/generate-from-html \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>請求書</h1>",
    "email": {
      "to": "customer@example.com",
      "subject": "請求書をお送りします",
      "body": "添付の請求書をご確認ください。"
    }
  }'

B) ダッシュボードで事前設定

メール通知設定で送信先・件名・本文テンプレートを設定すると、PDF生成のたびに自動でメール送信されます。

件名・本文では以下のプレースホルダーが使えます:

プレースホルダー	内容
`{{filename}}`	ファイル名
`{{file_size}}`	ファイルサイズ
`{{expires_at}}`	有効期限
`{{download_url}}`	ダウンロードURL

Webhook / Slack通知

GET/api/webhooks

POST/api/webhooks

Webhook URLを登録します。イベント発生時にPOSTで通知されます。

名前	型	必須	説明
`url`	string	o	通知先URL
`events`	array	o	通知イベント（下記参照）

対応イベント

イベント	説明
`pdf.generated`	PDF生成完了
`pdf.downloaded`	PDFダウンロード
`pdf.expired`	PDF期限切れ
`batch.completed`	バッチ処理完了

Slack連携

URLに Slack Incoming Webhook URL を指定すると、自動的にSlack Block Kit形式で通知されます。ダウンロードボタン付きのリッチな通知が届きます。

ダッシュボードからもWebhook・Slack通知の設定ができます。

署名検証

通常のWebhookでは X-Webhook-Signature: sha256=HMAC(payload, secret) ヘッダーが付与されます。

利用状況

GET/api/usage

今月の利用数・残数・プラン情報・有効機能を返します。

S3ストレージ連携

生成したPDFをAWS S3（またはS3互換サービス）に自動アップロードします。設定が有効な場合、PDFがローカルとS3の両方に保存され、レスポンスに s3_url が含まれます。

ダッシュボードから設定できます。APIでも操作可能です:

GET/api/storage-config

POST/api/storage-config

PUT/api/storage-config

DELETE/api/storage-config

名前	型	必須	説明
`driver`	string	o	`s3`
`config.bucket`	string	o	バケット名
`config.region`	string	o	リージョン
`config.key`	string	o	アクセスキーID
`config.secret`	string	o	シークレットキー
`config.endpoint`	string		カスタムエンドポイント（Wasabi等のS3互換サービス用）

認証情報はサーバー上で暗号化して保存されます。

エラーコード

ステータス	意味	対処
`401`	認証エラー	APIキーを確認してください
`403`	権限なし / 機能未有効	プランをアップグレード、またはIP制限を確認
`404`	リソース不明	ファイル名やIDを確認
`422`	バリデーションエラー	リクエストパラメータを確認
`429`	月間制限超過	翌月まで待つかプランをアップグレード
`500`	サーバーエラー	サポートにお問い合わせ

全てのエラーレスポンスは以下の形式です:

{ "success": false, "message": "エラーの説明" }