Parseur

🤖🧙parseur-py

parseur-py は、Parseur API を利用する最新の Python クライアントです。

プログラムから、またはコマンドラインから、メールボックス、ドキュメント、アップロード、ウェブフックを管理できます。

ドキュメント解析を大規模に自動化できるように設計された parseur-py を使えば、Parseur との連携をすばやく、簡単に、Python らしい方法で実現できます。

---

✨ 機能

✅ メールボックスの一覧表示、検索、並べ替え
✅ メールボックスの詳細とスキーマの取得
✅ ドキュメントの一覧表示、検索、フィルタリング、並べ替え
✅ ファイルまたはメールの内容によるドキュメントのアップロード
✅ ドキュメントの再処理、スキップ、コピー、削除
✅ リアルタイムイベント用のカスタムウェブフックの管理
✅ 一時的なウェブフックとトンネルを使ったリアルタイムイベントのリッスン
✅ 充実したコマンドラインインターフェイス（CLI）

---

⚠️ Localtunnel に関する免責事項

parseur listen コマンド（イベントリスナーのサポート付き）を使用すると、データは localtunnel サーバーを経由して転送されます。

これらのサーバーは Parseur とは無関係であり、Parseur のプライバシーポリシーまたはデータ処理契約の対象ではありません。

localtunnel 経由で送信されるデータは、エンドツーエンドで暗号化されません。

➡️ この機能は自己責任でご利用ください。

本番環境向けの構成では、localtunnel に依存せず、ご自身で安全なウェブフックエンドポイントを設定することを強くおすすめします。

---

🚀 クイックスタート

パッケージをインストールする

pip install parseur-py

イベントリスナーのサポートを含める場合（Flask + localtunnel）

pip install "parseur-py[listener]"

ソースからパッケージをインストールする

pip install -e .

ドキュメントをビルドする

pip install -r requirements-doc.txt
cd docs
make html

テストを実行する

ユニットテストは完全にオフラインで実行されます。

pytest

統合テストは実際の Parseur API に接続します。実際のリソースを作成・削除するため、認証情報が環境変数経由で指定されていない限り、テストはスキップされます（認証情報をコミットしたり、~/.parseur.conf に保存したりしないでください）。

PARSEUR_API_BASE=https://api.parseur.com \
PARSEUR_API_KEY=sk_your_key \
pytest tests/integration -v

---

設定を初期化する

Parseur API の認証情報を安全に保存します。

parseur init --api-key YOUR_PARSEUR_API_KEY

設定はデフォルトで次の場所に保存されます。

~/.parseur.conf

---

使用例

すべてのメールボックスを一覧表示します。

parseur list-mailboxes

メールボックス内のドキュメントを一覧表示します。

parseur list-documents 12345

メールボックスにファイルをアップロードします（解析が完了するまで待機し、進捗状況をリアルタイムで表示するには --wait を追加します）。

parseur upload-file 12345 ./path/to/document.pdf
parseur upload-file 12345 ./path/to/document.pdf --wait

メールボックスの結果をファイルとしてダウンロードします（デフォルトでは標準出力に出力します。--output も指定できます）。

parseur download-mailbox 12345 --format csv -o results.csv     # whole mailbox
parseur list-parser-fields 12345                               # find a table field id
parseur download-field 12345 PF951 --format xlsx -o lines.xlsx  # a table field

カスタムウェブフックを登録します。

parseur create-webhook --event document.processed --target-url https://yourserver.com/webhook --mailbox-id 12345

イベントをリアルタイムでリッスンします（[listener] が必要です）。

parseur listen --event document.processed --mailbox-id 12345

転送を有効にする場合：

parseur listen --event document.processed --mailbox-id 12345 --redirect-url http://localhost --redirect-port 8000

---

📜 CLI コマンド

次を実行します。

parseur --help

利用可能なコマンドの全一覧を確認できます。

主な機能

• init: API トークンと（任意の）ベース URL を設定します
• list-mailboxes: メールボックスを検索・並べ替えます
• get-mailbox: ID でメールボックスを取得します
• get-mailbox-schema: メールボックスの解析スキーマを取得します
• list-parser-fields: メールボックスで抽出されたフィールドを一覧表示します
• download-mailbox / download-field / download-export: 結果をファイル（csv/json/xlsx）としてダウンロードします
• list-export-configs: メールボックスのカスタムエクスポート設定を一覧表示します
• list-documents: 高度なドキュメント検索、絞り込み、並べ替えを行います
• get-document / get-document-logs: ドキュメントの詳細と処理ログを取得します
• reprocess-document / skip-document / copy-document / split-document / reverse-split-document / delete-document: ドキュメントのライフサイクルを操作します
• upload-file / upload-text: 新しいドキュメントをアップロードします（同期解析するには --wait を追加します）
• upload-folder: glob パスに一致するすべてのファイルをアップロードします
• create-webhook / get-webhook / list-webhooks / delete-webhook: カスタム Webhook 連携を作成、取得、一覧表示、削除します。
• enable-webhook / pause-webhook: 特定のメールボックスの Webhook を有効化または一時停止します。
• listen: 一時的な Webhook を作成し、イベントをリアルタイムで待ち受けます（リダイレクトとサイレントモードは任意）

---

🔎 高度な検索と絞り込み

メールボックスの一覧表示では、次の操作ができます。

• 名前またはメールアドレスのプレフィックスで検索
• 次の項目で並べ替え：
  • name
  • document_count
  • template_count
  • PARSEDOK_count（処理済み）
  • PARSEDKO_count（失敗）
  • QUOTAEXC_count（クォータ超過）
  • EXPORTKO_count（エクスポート失敗）

ドキュメントの一覧表示では、次の操作ができます。

• 次の項目を検索：
  • ドキュメント ID
  • ドキュメント名
  • テンプレート名
  • メールアドレス（from、to、cc、bcc）
  • ドキュメントメタデータのヘッダー
• 次の項目で並べ替え：
  • name
  • created（受信日）
  • 処理日
  • ステータス
• 次の日付で絞り込み：
  • received_after / received_before
• 解析結果をレスポンスに含める

---

⚡ Webhook のサポート

次のようなイベント向けに、カスタム Webhook を簡単に登録できます。

• document.processed
• document.processed.flattened
• document.template_needed
• document.export_failed
• table.processed
• table.processed.flattened

Webhook エンドポイントは Parseur のペイロードを含む POST 通知を受信するため、システムとリアルタイムに連携できます。

---

🤖 MCP サーバー（AI アシスタント）

Parseur は https://api.parseur.com/mcp で MCP サーバーをホストしています。この URL を MCP 対応の AI アシスタント（Claude、Codex、Cursor、…）に追加すると、そこから Parseur を操作できます。ローカルへのインストールは不要です。

---

🛠️ 設定

API トークンと設定は、シンプルな INI ファイルに保存されます。

[parseur]
api_token = YOUR_API_KEY
base_url = https://api.parseur.com

必要に応じて、呼び出し時に `--config-path` を設定することでパスをカスタマイズできます。

---

🐍 Python クライアントの使用方法

CLI に加えて、parseur-py は標準的な Python ライブラリです。例：

import parseur

parseur.api_key = "YOUR_API_KEY"

for mailbox in parseur.Mailbox.list():
    print(mailbox.name)

呼び出しごとの API キーの上書き

すべてのメソッドで任意の api_key 引数を指定でき、その呼び出しに限りグローバルな parseur.api_key より優先されます。複数アカウントやマルチテナントのコードで便利です。

parseur.Mailbox.list(api_key="sk_account_a")
parseur.Document.upload_file(123, "invoice.pdf", api_key="sk_account_b")

---

📖 ドキュメント

• Parseur 公式 API ドキュメント
• このパッケージは Parseur の REST API をベースに、ページネーション処理、スキーマのサポート、便利な CLI コマンドを追加しています。

---

💼 ライセンス

MIT License

---

🤝 貢献

貢献を歓迎します！次の手順でお願いします。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/foo）
3. 変更をコミットします（git commit -am 'Add foo'）
4. ブランチにプッシュします（git push origin feature/foo）
5. プルリクエストを作成します

---

✨ クレジット

Parseur チームが ❤️ を込めて開発しました。

---

Parseur は、メールやドキュメントからデータを自動抽出する最も簡単な方法です。データのコピー＆ペーストをやめて、ワークフローを自動化しましょう！