開発者向けの Invoice Radar プラグイン ハンドブックへようこそ!
このガイドは、さまざまなプラットフォームから請求書や領収書を取得するためのカスタム プラグインを作成するのに役立ちます。
Invoice Radar は、さまざまなプラットフォームから請求書や領収書を取得、ダウンロード、整理するのに役立つ文書自動化ツールです。
請求書レーダーについて詳しく見る
導入
はじめる
プラグインの構造
初めてのプラグインを作成する
便利なパターン
手順のリファレンス
JSON、HTML、CSS、JavaScript の基本的な知識。
テキスト エディターまたは IDE (VSCode、Sublime Text など)。
Invoice Radar は macOS または Windows にインストールされます。
Invoice Radar をダウンロードしてインストールします。
請求書レーダーへのアクセスをリクエストする
空のプラグインをダウンロードします。
空のプラグインをローカル マシンにダウンロードします。
ファイルの名前をyour-plugin-name.json
に変更します。
任意のフォルダに入れてください。
プラグインを請求書レーダーに追加します。
請求書レーダーを開きます。
設定に移動し、 Available Plugins
タブを選択します。
Choose Plugin Directory
選択し、プラグインを保存したフォルダーを選択します。
プラグインが利用可能なプラグインのリストに表示されます。
Invoice Radar のプラグインは JSON で記述され、特定の構造に従います。各プラグインは次のセクションで構成されます。
プラグインの説明:
メタデータ: 名前、説明、ホームページ URL など、プラグインに関する基本情報。
configSchema : プラグインに必要な構成プロパティ。
スクレイピング手順:
checkAuth : ユーザーがすでに認証されているかどうかを確認する手順。
startAuth : 認証プロセスを開始するステップ。
getDocuments : ドキュメントを取得してダウンロードする手順。
{ "$schema": "https://raw.githubusercontent.com/invoiceradar/plugins/main/schema.json", "id": "example", "name": "サンプル プラットフォーム", "description": "サービスの簡単な説明。"、"ホームページ": "https://example.com"、"checkAuth": [ { "アクション": "ナビゲート"、"URL": "https://example.com/dashboard" }、 { "アクション": "checkElementExists", "セレクター": "#ログアウトボタン" } ]、"startAuth": [ { "アクション": "ナビゲート"、"URL": "https://example.com/login" }、 { "アクション": "waitForElement"、"セレクター": "#account-summary"、"タイムアウト": 120000 } ]、"getDocuments": [ { "アクション": "ナビゲート"、"URL": "https://example.com/billing" }、 { "action": "extractAll", "selector": ".invoice-row", "variable": "invoice", "fields": { "id": { "selector": ".invoice-id" }, "日付": { "セレクター": ".invoice-date" }, "合計": { "セレクター": ".invoice-total" }, "url": { "セレクター": ".invoice-download", "属性": "href" } }, "forEach": [ { "アクション": "downloadPdf"、"url": "{{invoice.url}}"、"ドキュメント": "{{invoice}}" } ] } ] }
完全なスキーマはここにあります。
架空のサービスから請求書を取得する簡単なプラグインを作成してみましょう。
メタデータを定義します。
この情報は、Invoice Radar でプラグインを識別して表示するために使用されます。ホームページの URL は、サービスのファビコンを取得するために使用されます。
id
一意で小文字である必要があることに注意してください。
{ "id": "example-service", "name": "サービス例", "description": "サービスの簡単な説明", "homepage": "https://example.com"}
メタデータ フィールドについて詳しくは、こちらをご覧ください。
構成スキーマを定義します(オプション):
構成スキーマは、プラグインが機能するために必要なフィールドを定義します。この例では、認証のためにteamID
とpassword
必要です。
これらのフィールドは、Invoice Radar にプラグインを追加するときにユーザーに表示されます。
"configSchema": { "teamID": { "type": "string", "title": "チーム ID", "description": "請求書を取得するチームまたはアカウントの ID。", "required": true } }
構成スキーマフィールドの詳細については、こちらをご覧ください。
認証の確認:
checkAuth
は、ユーザーが認証されているかどうかを確認する手順が含まれています。これは、URL または要素の存在を確認することで実行できます。 checkAuth
内の最後のステップは検証ステップである必要があります。
これらのステップは、実行の開始時に実行されます。ユーザーがすでに認証されている場合、プラグインは認証プロセスをスキップし、ドキュメントの取得に直接進みます。
"checkAuth": [ { "アクション": "ナビゲート"、"URL": "https://example.com/dashboard" }、 { "アクション": "checkElementExists", "セレクター": "#ログアウトボタン" } ]
認証を開始します:
startAuth
認証プロセスを開始する手順が含まれています。これには、ログイン ページに移動し、ログイン成功インジケータを待つことが含まれる場合があります。
ブラウザは認証プロセス中に表示され、ユーザーがログイン フォームを操作できるようになります。
"startAuth": [ { "アクション": "ナビゲート"、"URL": "https://example.com/login" }、 { "アクション": "waitForElement"、"セレクター": "#account-summary"、"タイムアウト": 120000 } ]
ドキュメントをスクレイピング:
getDocuments
ドキュメントを取得してダウンロードする手順が含まれています。これには、請求ページへの移動、請求書の詳細の抽出、PDF のダウンロードが含まれる場合があります。
"getDocuments": [ { "アクション": "ナビゲート"、"URL": "https://example.com/billing" }、 { "action": "extractAll", "selector": ".invoice-row", "variable": "invoice", "fields": { "id": { "selector": ".invoice-id" }, "日付": { "セレクター": ".invoice-date" }, "合計": { "セレクター": ".invoice-total" }, "url": { "セレクター": ".invoice-download", "属性": "href" } }, "forEach": [ { "action": "downloadPdf", "url": "{{invoice.url}}", "document": { "type": "invoice", "id": "{{invoice.id}}", "日付": "{{invoice.date}}"、"合計": "{{invoice.total}}" } } ] } ]
これで完了です。 :
ファイルを保存し、Invoice Radar に追加します。これで、プラグインを実行してサービスから請求書を取得できるようになりました。
checkAuth
)ユーザーが認証されていない場合、多くのサービスは自動的にログイン ページにリダイレクトします。この動作を使用して、ユーザーが認証されているかどうかを確認できます。
{ "アクション": "ナビゲート", "url": "https://example.com/login"}, { "アクション": "checkURL", "url": "https://example.com/account", }
サービスによっては、認証されていない場合、ダッシュボードからログイン ページにリダイレクトされる場合があります。この場合、 checkURL
ステップを使用して、ダッシュボードにアクセスした後も URL が一致するかどうかを確認できます。
{ "アクション": "ナビゲート", "url": "https://example.com/dashboard"}, { "アクション": "checkURL", "url": "https://example.com/dashboard", }
glob パターンを使用して動的 URL ( https://example.com/dashboard/**
を照合できることに注意してください。
認証済み状態に固有のセレクターを使用して、ユーザーが認証されているかどうかを確認できます (ログアウト ボタンやプロファイル リンクなど)。
{ "アクション": "ナビゲート", "url": "https://example.com/home"}, { "アクション": "waitForElement"、"セレクター": "#ログアウトボタン"}
場合によっては、 checkElementExists
ステップの実行時に Web サイトが完全に読み込まれていないことがあります。これを回避するには、 waitForNetworkIdle
属性を使用して、ページが完全にロードされるまで待機します。
{ "アクション": "ナビゲート", "url": "https://example.com/home", "waitForNetworkIdle": true}, { "アクション": "checkElementExists", "セレクター": "#ログアウトボタン"}
startAuth
)ほとんどの認証プロセスは、ログイン ページに移動し、ログイン成功後に特定の要素が表示されるのを待つことから始まります。
認証プロセス中にブラウザが表示され、ユーザーがログイン フォームを操作できるようになります。認証フロー自体は自動化できますが、必須ではありません。
{ "アクション": "ナビゲート", "url": "https://example.com/login"}, { "アクション": "waitForElement"、"セレクター": "#logout-button"、"タイムアウト": 120000}
ユーザーにログインするのに十分な時間を与えるために、待機ステップに長いタイムアウト (デフォルトは 120 秒) を設定することをお勧めします。
このセクションでは、Invoice Radar のプラグインを作成するために使用できる手順の概要を説明します。各ステップは、自動化プロセス中に実行できる特定のアクションを表します。
ナビゲーションの手順
ナビゲート ( navigate
)
URL を待つ ( waitForURL
)
要素の待機 ( waitForElement
)
ナビゲーションを待つ ( waitForNavigation
)
ネットワークアイドル状態を待つ ( waitForNetworkIdle
)
インタラクションのステップ
要素をクリック ( click
)
テキストを入力 ( type
)
ドロップダウンを選択 ( dropdownSelect
)
JavaScript を実行する ( runJs
)
検証手順
要素の存在を確認する ( checkElementExists
)
URL を確認する ( checkURL
)
JavaScript を実行する ( runJs
)
データ抽出手順
抽出 ( extract
)
すべて抽出 ( extractAll
)
ドキュメントの取得手順
PDF をダウンロード ( downloadPdf
)
PDF のダウンロードを待ちます ( waitForPdfDownload
)
ページを PDF として印刷 ( printPdf
)
Base64 PDF をダウンロード ( downloadBase64Pdf
)
条件付きロジックのステップ
もしも ( if
)
その他の手順
スリープ ( sleep
)
スニペット
Stripe URL から請求書を取得 ( getInvoiceFromStripeUrl
)
Stripe カスタマーポータルから請求書を取得する ( getInvoicesFromStripeBillingPortal
)
navigate
)指定された URL に移動し、ページが読み込まれるのを待ちます。デフォルトでは、最初のページの読み込みのみを待機し、後続の AJAX リクエストは待機しません。
{ "アクション": "ナビゲート"、"URL": "https://example.com"}
waitForNetworkIdle
true
に設定すると、続行する前にページが完全にロードされていることを確認できます。
{ "アクション": "ナビゲート"、"url": "https://example.com/dashboard"、"waitForNetworkIdle": true}
知っておくとよいこと:
相対 URL がサポートされており、現在のページに基づいて解決されます。
ナビゲート アクションは、最初のページの読み込みのみを待機し、後続の AJAX リクエストは待機しません。
waitForURL
)現在の URL が指定された URL と一致するまで待機します。オプションでタイムアウトも指定できます。ワイルドカードをサポートします。
{ "アクション": "waitForURL", "url": "https://example.com/profile/**", "タイムアウト": 3000}
waitForElement
)指定されたセレクターがページに表示されるまで待機します。オプションでタイムアウトも指定できます。
{ "アクション": "waitForElement"、"セレクター": "#example"、"タイムアウト": 3000}
waitForNavigation
)ページナビゲーションが行われるのを待ちます。このステップは、ページが完全にロードされるまで待機しません。そのためには、waitForNetworkIdle ステップを使用します。タイムアウトはオプションで、デフォルトは 10 秒です
{ "アクション": "waitForNavigation"、"タイムアウト": 10000}
waitForNetworkIdle
)ネットワークがアイドルになるまで待機します。これは、ページがすべてのリソースの読み込みを完了していることを確認したい場合に便利です。 500 ミリ秒間ネットワーク要求がなくなると、この手順は完了します。タイムアウトはオプションで、デフォルトは 15 秒です。
navigate
ステップにはwaitForNetworkIdle
オプションがあり、これをtrue
に設定すると同じ動作が得られます。
{ "アクション": "waitForNetworkIdle"、"タイムアウト": 10000}
click
)ページ上の指定されたセレクターで指定された要素をクリックします。
{ "アクション": "クリック"、"セレクター": "#ボタン"}
type
)ページ上の指定されたセレクターで指定された要素に指定されたテキストを入力します。
{ "アクション": "タイプ"、"セレクター": "#input"、"値": "Hello World"}
dropdownSelect
)ページ上の指定されたセレクターで指定されたドロップダウンから指定された値を選択します。選択は、オプションのvalue
属性に基づいて行われます。
{ "アクション": "dropdownSelect"、"セレクター": "#dropdown"、"値": "オプション 1"}
runJs
)指定された JavaScript をページ コンテキストで実行します。 Promise が返された場合は待機されます。
スクリプトの結果を後続のステップで使用する場合は、代わりに抽出ステップを使用してください。
{ "アクション": "runJs", "スクリプト": "document.querySelector('#example').click();"}
これらの手順は、ユーザーが認証されているかどうかを確認するためにcheckAuth
内で使用されます。
checkElementExists
)指定されたセレクターがページ上に存在するかどうかを確認します。通常、認証チェックに使用されます。
{ "アクション": "checkElementExists", "セレクター": "#example"}
checkURL
)現在の URL が指定された URL と一致するかどうかを確認します。 https://example.com/dashboard/**
のようなワイルドカード パターンをサポートします。
{ "アクション": "checkURL", "url": "https://example.com"}
runJs
) runJs
ステップは検証ステップとしても使用できます。真または偽の値を返すスクリプトを実行すると、ユーザーが認証されているかどうかを確認できます。
{ "アクション": "runJs", "スクリプト": "document.cookie.includes('authToken');"}
これらのステップは、項目のリストや単一の値などのデータをページからロードし、後続のステップで使用するために使用されます。
extract
)ページから 1 つのデータを抽出し、変数に格納します。
CSS フィールドの使用:
{ "action": "extract", "variable": "account", "fields": { "id": "#team-id", "name": "#team-name", "url": { "セレクター": "#チームリンク"、"属性": "href" } } }
この例では、 account
変数名として使用され、フィールドid
、 name
、およびurl
CSS セレクターを使用して抽出されます。これらは、 {{account.id}}
、 {{account.name}}
、および{{account.url}}
プレースホルダーを使用して後続のステップで使用できます。
JavaScript の使用:
{ "アクション": "抽出"、"変数": "トークン"、"スクリプト": "localStorage.getItem('authToken')"}
この例では、JavaScript を使用して抽出されるtoken
変数を作成します。この値には{{token}}
プレースホルダーを使用してアクセスできます。オブジェクトを返すことも可能です。
extractAll
)ページからデータのリストを抽出し、項目ごとに指定された手順を実行します。これは通常、請求書のリストを反復処理してダウンロードするために使用されます。
selector
に一致する各要素について、フィールドが抽出され、 forEach
ステップで使用可能なvariable
に保存されます。
知っておくとよいこと:
fields
オブジェクト内の各セレクターは、一致した要素に自動的にスコープされます。
variable
フィールドはオプションです。指定しない場合、抽出されたデータはデフォルトの変数item
に保存されます。
現在のインデックスには、 {{index}}
プレースホルダーを使用してアクセスできます。 0 から始まり、項目ごとに増加します。
CSS フィールドの場合:
{ "action": "extractAll", "selector": ".invoice-list .invoice-item", "variable": "invoice", "fields": { "id": "td.invoice-id", " date": "td.invoice-date"、"total": "td.invoice-total"、"url": { "selector": "a.invoice-link"、"attribute": "href" } }, "forEach": [ { "アクション": "ナビゲート"、"url": "{{invoice.url}}" }、 { "アクション": "ダウンロードPdf"、"請求書": "{{請求書}}" } ] }
JavaScript を使用する場合:
JavaScript を使用する場合、結果はオブジェクトまたは値の配列である必要があります。結果が約束であれば、それを待ちます。
{ "アクション": "extractAll", "スクリプト": "Array.from(document.querySelectorAll('#年セレクターオプション')).map(option => option.value);", "variable": "年", "forEach": [ { "アクション": "dropdownSelect"、"セレクター": "#year-selector"、"値": "{{年}}" } ] }
ページネーション
実験的なサポートですが、まだ文書化されていません。
これらの手順は、ドキュメントをダウンロードし、Invoice Radar で処理するために使用されます。すべての手順では、ドキュメントのメタデータを含むdocument
オブジェクトを引数として渡す必要があります。
document
引数には次のフィールドがあります。
必須
id
: 一意のドキュメントID
例: INV-123
または123456
date
: 文字列としての請求書の日付
例: 2022-01-01
01/01/2022
、またはJanuary 1, 2022
推奨
total
: 通貨を含む請求書の合計金額。
例: $100.00
または€100.00
または100 EUR
または100,00€
組み込みのパーサーは、文字列から金額と通貨を抽出しようとします。
オプション
type
: ドキュメントのタイプ(オプション。デフォルトはauto
)
auto
、 invoice
、 receipt
、 refund
other
に設定できます。
metadata
: ドキュメントの追加メタデータ(オプション)
例{ "orderNumber": "12345" }
すべてのフィールドを個別に渡すことも、オブジェクトにすべての必須フィールドが含まれている場合はオブジェクト全体を渡すこともできます。
たとえば、別のフィールドを使用する場合:
"document": { "id": "{{item.invoiceId}}"、"date": "{{item.date}}"、"total": "{{item.amount}} {{item.currency }}", "タイプ": "請求書"}
たとえば、オブジェクトにすべての必須フィールドが含まれている場合は、それを直接渡すことができます。
"ドキュメント": "{{item}}"
downloadPdf
)指定された URL から PDF をダウンロードします。
{ "action": "downloadPdf", "url": "https://example.com/invoice.pdf", "document": { "id": "{{item.invoiceId}}", "date": "{{item.date}}"、"合計": "{{item.total}}" } }
waitForPdfDownload
)PDFのダウンロードを待ちます。タイムアウトのデフォルトは 15 秒です。
{ "アクション": "waitForPdfDownload"、"タイムアウト": 10000、"ドキュメント": { "id": "{{item.invoiceId}}"、"日付": "{{item.date}}"、"合計": "{{item.total}}" } }
printPdf
)現在のページを PDF ファイルに印刷します。
{ "action": "printPdf", "document": { "id": "{{item.invoiceId}}"、 "date": "{{item.date}}"、 "total": "{{item 。合計}}" } }
downloadBase64Pdf
)Base64 でエンコードされた文字列から PDF をダウンロードします。
{ "action": "downloadBase64Pdf", "base64": "{{item.base64String}}", "document": { "id": "{{item.invoiceId}}", "date": "{{item .date}}"、"合計": "{{item.total}}" } }
if
)条件が true の場合、指定されたステップを実行します。条件が false の場合、 else
ステップが実行されます。
{ "アクション": "if", "スクリプト": "'{{invoice.url}}'.includes('pdf')", "then": [ { "アクション": "クリック"、"セレクター": "#example" } ]、 "それ以外": [ { "アクション": "ナビゲート"、"URL": "https://example.com/fallback" } ] }
sleep
)ミリ秒単位で指定された時間待機します。これは一般に推奨されません。ほとんどの場合、waitForElement、waitForURL、または waitForNetworkIdle ステップを使用することをお勧めします。
{ "アクション": "睡眠"、"継続時間": 1000}
スニペットは、一般的なタスクを簡素化する事前に構築されたステップのセットです。特定のスニペットの手順は開発者ツール内に表示されます
現在、カスタム スニペットを作成することはできません。スニペットとして役立つと思われる共通のタスクがある場合は、GitHub で問題を作成してください。
getInvoiceFromStripeUrl
)Stripe 請求書 URL から請求書を抽出します。
{ "action": "runSnippet", "snippet": "getInvoiceFromStripeUrl", "args": { "url": "https://invoice. Stripe.com/i/inv_123" } }
getInvoicesFromStripeBillingPortal
)Stripe 請求ポータルから利用可能な請求書を抽出します。
{ "action": "runSnippet", "snippet": "getInvoicesFromStripeBillingPortal", "args": { "url": "https:// Stripe-portal.example.com/billing" } }
場合によっては、API からデータをフェッチするステップ内でフェッチ リクエストを実行する必要がある場合があります。これを行うには、 extractAll
アクションを使用できます。
{ "アクション": "extractAll"、"変数": "請求書"、"スクリプト": "fetch('https://example.com/api/invoices').then(res => res.json()) " "forEach": [ { "action": "downloadPdf", "url": "{{invoice.url}}", "document": { "id": "{{invoice.id}}", "date": "{{invoice .date}}", "total": "{{invoice.total}}" } } ] }
これにより、フェッチ リクエストが実行され、結果が JavaScript オブジェクトとして返されます。
内のステップを実行します。シナリオによっては、 要素内でステップを実行する必要がある場合があります。これを行うには、ステップで
iframe
属性を使用します。
{ "アクション": "クリック", "セレクター": "#button-inside-iframe", "iframe": true},
iframe
true
に設定すると、Invoice Radar はページ上の最初の要素を見つけて、その中のステップを実行します。
iframe のsrc
属性内に含まれる文字列を使用して、特定の iframe をターゲットにすることもできます。
{ "アクション": "クリック"、"セレクター": "#button-inside-iframe"、"iframe": "iframe.example.com"},